Credentials

A credential is a login or API key that nodes sign their requests with: a bearer token, an API key header, an OAuth2 sign-in to Google, a Telegram bot token, an SMTP server. You save it once in Dataset › Credentials, pick it in a node, and the run gets it ready to use. The values never travel back to the page.

Add a credential

1. Go to Dataset › Credentials and click Add credential.
2. Pick the Type. The form shows that type's fields.
3. Give it a Name and fill the fields. Passwords and tokens are saved encrypted.
4. Set Who can use it, like every dataset.
5. Click Add.

When you edit a credential later, its password fields start blank and show a hint (Saved (sk-…a1b2)). Leave a field blank to keep the saved value.

Types

The types without HTTP auth (Telegram, Discord webhook, SMTP, IMAP) are for the made for them. HTTP request offers only the types that sign a request.

External secrets

On Enterprise, a credential's value can live in your own secret manager and be read at run time:

1. Add a HashiCorp Vault (address, token, KV mount, namespace), AWS Secrets Manager (region, access key; Endpoint only for a VPC endpoint or LocalStack) or Google Secret Manager (service account key JSON, project) credential.
2. In any other credential, type a value as secret://<that credential's name>/<path>#<key>, for example secret://Vault/shop/api#token. No #key: the whole secret.

Values are fetched every time the credential is resolved (each run, each test) and never stored in Mooflair.

Connect an OAuth2 credential

An OAuth2 credential (OAuth2, Google) holds your OAuth app's Client ID and Client secret, and signs in once:

1. In your OAuth app at the service (for Google, the Google Cloud console), register this callback URL: <your mooflair URL>/api/credential/oauth/callback. The dialog shows it.
2. Save the credential, then choose Connect in its ⋯ menu.
3. Sign in at the service and allow access. You come back to Credentials with Connected.

How it works:

• GET /api/credential/oauth/start?id=<credential>&workspace=<slug> sends you to the service with a signed state (10 minutes), plus PKCE when the type asks for it (Google does; for OAuth2 set PKCE to yes).
• GET /api/credential/oauth/callback trades the code for tokens and saves them sealed.
• Changing the client, the URLs or the scopes disconnects the credential, so connect it again after.
• An access token with a minute or less left is refreshed when a run starts (mooflair resolves it for the engine). A node that gets 401 mid-run can ask for a fresh one (see ).

Test and usage

• Test sends the type's test request with the credential and checks the answer: a 2xx status, and for some types a field that must be set (ok, id). A type without a test request only checks that the credential resolves, which for OAuth2 means it's connected and its token can be refreshed. A passing test sets Tested.
• Flows using it lists the flows whose nodes pick it. Removing a credential that's in use stops those flows from running until you pick another.
• Removing a credential sends it to the for 30 days.

In a run

A node field of kind dataset.credential holds the credential's id. When a run starts, mooflair:

1. checks that the person behind the run may use it, and that its type fits the field;
2. refreshes an OAuth2 token that's about to expire;
3. puts it in the node's secrets, resolved:

type TCredentialResolved = {
	id: string;
	type: string;                                                   // "http/bearer"
	value: Record<string, string>;                                  // its fields, passwords opened
	auth: { header: Record<string, string>; query: Record<string, string> }; // add these to a request
	oauth: { token: string } | null;                                // the OAuth2 access token
};

A node reads it from ctx.field.<field id>. Its values are masked in every log line, like every other secret.

// ** In a script node: call an API with a credential field "credential"
const credential = ctx.field.credential;
const url = new URL("https://api.example.com/items");
for (const [key, value] of Object.entries(credential.auth.query)) url.searchParams.set(key, value);
const response = await fetch(url, { headers: credential.auth.header });

Where it's kept

The re-seals all three. Exports leave out the values unless Include passwords and keys is on, and never include OAuth2 tokens, so connect again after an import.

Add a type

A type is one folder, src/lib/credential/<service>/<name>/index.ts, plus a line in src/lib/credential/index.ts. Its labels go under component.credential.<service>.<name> (name, description, field.<id>):

export const credentialAcmeKey = {
	type: "acme/key",
	icon: "key-round",
	field: [{ id: "key", kind: "password", required: true }],
	auth: { kind: "header", header: { "X-Acme-Key": "{key}" } },
	test: { method: "GET", url: "https://api.acme.com/me", check: "id" },
} satisfies TCredentialDefinition;

{<field id>} fills from its values, and {oauth.token} is the OAuth2 access token. Fields can use show like node fields.

FAQ

Can I see a saved token again?

No. Passwords and tokens are only shown as a hint. To change one, type the new value. To keep it, leave the field blank.

Why can't I pick my Telegram credential in HTTP request?

HTTP request lists only the credentials that sign a request (headers, query, basic, bearer, OAuth2, custom JSON). A Telegram bot token goes in the URL path, so the Telegram nodes use it instead.

My Google credential says "sign-in expired".

Google gave no refresh token, or revoked it. Choose Connect again. The Google type asks for offline access and consent each time, so a new connect returns a refresh token.