Credentials

A credential is a named, template-shaped bundle of secrets — a bot token, an API key pair, an OAuth2 client — stored encrypted in the Nucleus vault. Workflows never contain secret values; they contain references like ${credential.telegram-bot.botToken} that are resolved at the start of every run. That one design decision means exported workflows are safe to share, deployed apps carry no baked-in secrets, and rotating a key is a one-place edit.

Admin → Credentials is the home screen:

The credentials table in the Admin area
Every credential with its template, OAuth status (where applicable), Used-by count, last access, creation date and creator. Every column sorts and filters; the row actions are edit, duplicate, delete.

Create one from a template

  1. Click New credential.
  2. Pick a template — Telegram bot, S3-compatible storage, HTTP/JSON API, SQL, SMTP, OAuth2 providers, and more. The template defines the fields (and which of them are secret).
  3. Name it. The name is how workflows reference it — ${credential.<name>.<field>} — so pick something stable like telegram-bot or prod-postgres.
  4. Fill the fields and create.
The new credential modal with the template selector
The create modal. The template choice shapes the form — and for OAuth2 templates, the modal notes that tokens come from the provider via Connect after creation.

Secrets stay masked

Open an existing credential and the secret fields come back redacted — the UI never ships stored secret values back to the browser. Leave a secret blank when editing and the stored value is kept; type into it to replace it.

Editing the google-oauth2 credential with masked secrets and a Connect button
Editing the real google-oauth2 credential: the client secret is masked, managed token fields are handled for you, and the Connect button starts the consent flow. The status badge shows Disconnected / Connected (with expiry) / error.

The OAuth2 Connect flow, start to finish

OAuth2-kind credentials (Google, and the other preset providers) don’t store a long-lived secret you paste — they store a client id + client secret you create at the provider, and the tokens are issued by the provider through a consent flow:

  1. Create the OAuth client at the provider (for Google: an “OAuth client ID” of type Web application) and register the redirect URI https://<your-nucleus>/api/oauth/callback — the exact origin you browse the Nucleus at.
  2. Create the credential from the OAuth2 template, pasting client id + secret.
  3. Open the credential and click Connect. The Nucleus builds a signed, single-use, PKCE-protected authorization URL and opens the provider’s consent screen in a new tab:
The Google sign-in screen opened by the Connect button
The real consent screen, as opened by Connect. Sign in, approve the scopes, and the tab closes itself — the credentials page polls and flips the badge to Connected.
  1. Approve. The provider redirects back to the Nucleus callback, which validates the signed state, exchanges the code, stores the tokens in the managed fields, and marks the credential Connected — with the access-token expiry shown in the badge tooltip.

Refresh is automatic: whenever a run resolves a near-expiry OAuth2 credential, the Nucleus refreshes the access token first — in the editor’s test runs and in deployed apps.

Using credentials in a workflow

Connection-shaped nodes carry a credential picker at the top of their properties panel. Pick a credential and the node’s secret fields are provided by it — the field shows a quiet “provided by credential” hint instead of a value. The + New button creates a credential right there, without leaving the editor.

A node's properties panel with the credential picker engaged
The picker on the Telegram trigger: the bot token field carries ${'${credential.telegram-bot.botToken}'} — a reference, resolved at run start, never the value.

You can also type references by hand into any text field — ${credential.<name>.<field>} — and reference credentials by id or name interchangeably.

Used-by tracking

The Used by column counts the workflows referencing each credential — click it for the list, with a deployment marker when one of them is live on a host:

The Used-by popover listing workflows that reference a credential
“Used by” opens the referenced-by list. Deleting a credential that's still referenced is guarded — the product tells you exactly which workflows would break.

How deployed apps get secrets

Deployed apps dial home: at the start of every run the app asks the Nucleus to resolve its ${credential.*} / ${variable.*} references, receives a short-lived scoped lease (≈60s), substitutes the values in memory, and runs. Secrets are never written into the artifact, the container image, or the host’s disk. (This is why the Nucleus needs a routable FLOWDROME_NUCLEUS_PUBLIC_URL when hosts live on other machines.)

Next