Reuse credentials with scoped connections
Understand connections as reusable, scoped credentials, and when to use account scope versus workspace scope.
A connection is a stored credential to a third-party app. When a node in your workflow needs to call HubSpot, send a Slack message, or charge a card through Stripe, it authenticates with a connection. You create the credential once, and every node that talks to the same app reuses it.
Two ideas make connections worth understanding before you build. Connections are reusable, so you authorize an app a single time rather than once per node, and connections are scoped, so you decide whether a credential belongs to one client or is shared across every client you manage.
What a connection holds
A connection records who you are to an external app, not the data that flows through it. Each connection carries:
- The app it authenticates against (HubSpot, Slack, Stripe, and so on).
- A label, the name you see when picking the connection on a node.
- A credential kind, which is how the app authenticates you. The kinds are OAuth 2.0, API Key, Basic Auth, DSN, and Custom. The two you create directly in the builder are OAuth 2.0 and API Key.
- A status that reflects the credential's health.
- A scope, which decides which workspaces can use the credential.
The secret itself, an OAuth token or an API key, is never stored on the part of the connection your browser can read. The connection holds a reference to the secret in an encrypted store, and the platform retrieves the value only at run time. Your browser never receives the decrypted credential. For how that storage works, see How credentials are stored.
Connections are created inside the builder
There is no separate settings screen where you browse apps and click Connect. You create a connection where you need it: on the node that authenticates against the app, inside the visual workflow builder.
When you add an app action or app trigger and open its panel, an authentication section appears. From there you either pick an existing connection or run a connect flow that opens a dialog titled "Connect New Account". The dialog walks you through one of three shapes depending on how the app authenticates:
- OAuth 2.0. You are redirected to the app's consent screen in a popup window, you authorize access, and the connection is created when the popup reports back.
- API key. You name the connection, paste your token or key into the form, and save.
- Apps that need an extra field. Some apps ask for your account's subdomain, domain, or region in addition to OAuth or a key. Freshdesk, for example, asks for your Freshdesk subdomain. That field is part of the same connect form, not a separate auth type.
The step-by-step version of all three flows lives in Connect an account. This page is about the model underneath them.
The connect dialog labels each credential an "account" in its button text, for example "Connect New Account" and "Select an account". The underlying object is a connection. The two words point at the same thing: the verb is "connect an account," the noun is "a connection."
Reuse: connect once, select everywhere
Once a connection exists, you do not recreate it for the next node. The connection has an identity, and each node stores a reference to it. On any node that authenticates against the same app, you open the picker and select the connection you already made. The same connection can back any number of nodes across any number of workflows in that workspace.
The picker only offers connections that fit the node. It filters to connections for the right app, scoped to the workspace you are working in, and compatible with the authentication method the node requires. You will not see a Stripe connection offered on a Slack node, or a connection from another workspace.
Reconnecting the same external account does not pile up duplicates. If you run the connect flow again for an account you have already connected, the platform recognizes the same external identity and updates the existing connection instead of creating a second one. That is what makes reauthorizing after an expired token a clean operation rather than a cleanup job.
Scope: who can use a connection
Scope is the field that decides which workspaces a connection serves. It has two values, and it defaults to Workspace.
A quick orientation on the names: an Account is your top-level organization, and a Workspace is a space inside it, typically one per client. The Account, Workspace, User hierarchy explains how the two layers compose.
Workspace scope is the default and the common case. The credential belongs to one workspace and is usable only inside it. This is the right scope for a client's own system-of-record credentials: the client's HubSpot, their Stripe, their Twilio. Each client's connection stays isolated to that client's workspace. A workspace admin creates it.
The two scopes differ in who can create them and how they reach a workspace. A workspace-scoped connection lives in that one workspace. An account-scoped connection belongs to no single workspace and reaches each workspace through a separate grant that binds it there. A grant can carry a per-workspace monthly spend cap, which is how account-shared model keys stay metered per client.
Connection status and health
A connection's status tells you whether it can authenticate right now.
| Status | Meaning |
|---|---|
pending | Created but not yet usable. This is the starting status before the connect flow finishes. |
active | Healthy and ready to authenticate node calls. |
error | The credential failed and needs attention. |
revoked | The credential was disconnected and no longer authenticates. |
For OAuth connections, you do not refresh tokens by hand. The platform refreshes them automatically before they expire. You only need to act when a refresh fails permanently, which is the one case below.
When a connection needs reauthorization
If an OAuth token can no longer be refreshed, for example because the user revoked access on the app's side or changed their password, the connection stops being able to authenticate. The platform raises a reauthorization alert, and a banner appears in the workspace reading "A connection needs to be reauthorized" (or, for several at once, "N connections need to be reauthorized").
Runs that depend on the failed connection wait rather than fail outright; a step can park in a waiting state on a connection until the credential is healthy again. Reconnecting the same account through the connect flow updates the existing connection in place and lets the parked work continue. The recovery walk-through is in Reconnect an integration.
Limits worth knowing
- There is no general workspace-wide "all my connections" dashboard. You manage connections in three places: the picker inside the builder, the LLM Keys page for model-provider keys, and the client portal at
/portal/connections, where a client can rotate or revoke the OAuth connections they authorized. - Account-scope sharing through grants is currently surfaced for model-provider keys on the LLM Keys page. Do not plan around sharing an arbitrary app connection across workspaces from a general control yet.
- Basic Auth, DSN, and Custom credential kinds exist in the data model, but the in-builder connect dialog only creates OAuth 2.0 and API Key connections.
Related
- Connect an account walks the three connect flows step by step.
- How credentials are stored covers encryption, rotation, and revocation.
- Triggers and actions explains the nodes that use connections.