Credentials overview

Credentials are the stored connections workflows use to talk to third-party services — see the credentials guide for how they’re created and secured, and the catalog for every supported type. This page covers the two things you need when wiring credentials into API calls: who owns a credential and the UI key reference format.

Ownership

Every credential belongs to exactly one organization — there is no personal credential store. A connection you add is usable by that organization’s members and by every automation it runs, which is what makes a flow keep working when the person who set it up is away.

Owner	Created in	API surface
Organization	The organization’s Credentials page	/organizations/{organizationId}/credentials

Ownership is enforced on every query: a credential is only ever resolved by (id, organization id) together, so a credential ID leaked from another organization simply resolves to not-found.

The UI key

Wherever a credential is referenced — never its contents — BlockNext uses one canonical string format, called the UI key:

credential:organization:<uuid>

credential:organization:019fc6d8-16dc-7034-b23c-4f23e6ce0a41

Credentials are owned by an organization — that is the only scope, and it is what keeps a connection usable by every member and every automation of that organization rather than by one person.

Every credential’s API response carries its uiKey, and the platform surfaces it wherever a reference is expected — the run-time credential picker binds with it, and the flow editor’s API Trigger panel prefills a placeholder for each node that needs one.

References are the whole point of the security model: a workflow, an API request, or an MCP call only ever carries this opaque string. The runtime parses it, checks the scope, loads the credential for that owner, and decrypts it just-in-time for the node execution — secret material never crosses the boundary in either direction.

Where you use it

API trigger — the request body maps each node’s supported credential type to a UI key:

{
  "runtimePrompt": "Summarize today's updates",
  "nodes": [
    {
      "id": "2",
      "nodeId": "slack_send_message",
      "credentials": { "slack_oauth2": "credential:organization:<uuid>" }
    }
  ]
}

MCP tools — every tool that talks to an external service has a required credentials parameter whose values must match ^credential:organization:[0-9a-fA-F-]+$. See Using the MCP server.

In both cases the reference must belong to the calling organization: a key resolves only its own organization’s credentials, and anything else is rejected before a secret is touched.

Owner vs platform credentials

Independent of who owns it, a credential’s source says who supplies the secret material:

Source	Secret material
owner	You paste your own API key, or complete OAuth with your own client
platform	The self-hosting operator ships a managed OAuth app (via PLATFORM_CREDENTIALS_* env vars); you only click through consent, and only the acquired token is stored on your credential

A credential type advertises platform support automatically when the host has configured it — nothing to set manually.