Connections

A connection is an authenticated credential set that links an app to an external service. When a flow step or action call needs to interact with an external API, it uses a connection to provide the required authentication.

Connections are runtime data — they are created per organization and per user, and their credentials are stored securely in encrypted storage.

How connections work

1. An integration defines auth methods — the authentication schemes it supports (OAuth2, API Key, etc.)
2. A user creates a connection for a specific auth method, providing their credentials
3. When an action is called with a connectionId, the platform retrieves the connection's credentials and injects them into the API request

Action call (with connectionId)
  → Load connection credentials
    → Inject into HTTP request (header, query, body)
      → Send authenticated request

Connection types

The type of connection depends on the auth method defined in the integration:

OAuth2

For integrations that use OAuth2 authentication:

1. Initiate flow — the user is redirected to the external service's authorization page
2. User authorizes — the user grants access to the requested scopes
3. Callback — the platform receives the authorization code
4. Token exchange — the platform exchanges the code for access and refresh tokens
5. Store — tokens are encrypted and stored as the connection's credentials

The platform handles token refresh automatically. When an access token expires, the refresh token is used to obtain a new one before the API call is made.

API Key

The user provides an API key, which is stored encrypted and injected into requests according to the integration's configuration (as a header, query parameter, or cookie).

Basic Auth

The user provides a username and password, which are stored encrypted and sent as HTTP Basic Authentication.

Bearer Token

The user provides a token, which is stored encrypted and sent in the Authorization: Bearer {token} header.

Custom

For authentication schemes that don't fit standard patterns. The integration defines custom credential fields, and the platform stores and injects them according to the integration's configuration.

Credential storage

Connection credentials are stored using the platform's secrets system:

• All credential values are encrypted at rest
• Secrets are scoped to the organization
• Only the platform's execution engine can access decrypted values
• Credentials are never exposed in API responses or logs

Connection management

Creating a connection

Connections are created through the platform UI or API. The process depends on the auth method:

• OAuth2 — initiates the authorization flow (redirect → authorize → callback)
• API Key / Bearer / Basic — user provides credentials directly in a form
• Custom — user fills in the fields defined by the auth method's params schema

Testing a connection

After creation, connections can be tested to verify that the credentials are valid. Testing makes a simple API call using the connection and reports success or failure.

Using a connection

Connections are referenced by their ID. When calling an action:

{
  "actionIdentifier": "...",
  "connectionId": "conn_abc123",
  "input": { ... }
}

In flow steps, the connection ID is configured on each step that needs external authentication.

Revoking a connection

Deleting a connection removes the stored credentials. For OAuth2 connections, the platform can also revoke the tokens with the external service.

Scope

Connections are scoped to:

• Organization — credentials are accessible only within the organization where they were created
• User — the user who created the connection is its owner

Multiple connections can exist for the same integration and auth method — for example, different team members connecting to the same CRM with their own credentials.

Related concepts

• Integrations — where auth methods are defined
• Actions — how connections are used during action execution
• Flows — using connections in flow step configurations