External Integrations

Manage external integration credentials for scoped third-party access to external user session creation.

External integration credentials let you grant third-party systems scoped access to create external user sessions on behalf of your workspace. Each credential is bound to a specific integration and restricted to a set of services, so the third party can only create sessions for the services you explicitly allow.

This is useful when you want an external system - such as a partner scheduling platform or a customer portal - to initiate conversations with your agent without giving it full service account privileges.

Key Concepts

• Integration-scoped. Each credential belongs to a specific integration in your workspace.

• Service-restricted. The credential includes a list of service IDs. It can only create external user sessions for those services.

• Rotatable. You can rotate the client secret without changing the credential ID or client ID. The previous secret is immediately invalidated.

• Revocable. Revoking a credential permanently disables it. Revoked credentials cannot authenticate or create sessions.

• One-time secret. The client secret is returned only at creation and rotation. Store it securely - it cannot be retrieved later.

Endpoints

Method	Path	Description
POST	/v1/{workspace_id}/external-integrations/{integration_id}/credentials	Create credential
GET	/v1/{workspace_id}/external-integrations/{integration_id}/credentials	List credentials
POST	/v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id}/rotate	Rotate credential secret
DELETE	/v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id}	Revoke credential

Create Credential

POST /v1/{workspace_id}/external-integrations/{integration_id}/credentials

Creates a new external integration credential and returns the client ID and client secret. The client secret is only returned once - store it securely.

Request Body

Field	Type	Required	Description
service_ids	array of UUIDs	Yes	Services this credential can create external user sessions for. Minimum 1, maximum 100. No duplicates.
name	string	No	Human-readable name for the credential
expires_at	datetime	No	Optional expiration timestamp

Response (201)

Returns a credential object and the client_secret.

Credential object:

Field	Type	Description
id	UUID	Credential identifier
workspace_id	UUID	Workspace the credential belongs to
integration_id	UUID	Integration the credential is bound to
client_id	string	Client ID for authentication
service_ids	array of UUIDs	Allowed service IDs
name	string or null	Human-readable name
is_active	boolean	Whether the credential is active
expires_at	datetime or null	Expiration timestamp
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp
rotated_at	datetime or null	Last rotation timestamp
revoked_at	datetime or null	Revocation timestamp

Field	Type	Description
client_secret	string	Client secret (returned only at creation and rotation)

Errors

Status	Error	Description
404	Not Found	Integration does not exist in the workspace
422	Validation Error	Invalid service IDs, duplicates, or empty list

List Credentials

GET /v1/{workspace_id}/external-integrations/{integration_id}/credentials

Returns all external integration credentials for the specified integration, ordered by creation time (newest first).

Response (200)

Array of credential objects (same fields as the create response credential object, without client_secret).

Errors

Status	Error	Description
404	Not Found	Integration does not exist in the workspace

Rotate Credential

POST /v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id}/rotate

Generates a new client secret for an existing credential. The previous secret is immediately invalidated. The credential ID and client ID remain unchanged.

Response (200)

Same structure as the create response, including the new client_secret.

Errors

Status	Error	Description
404	Not Found	Credential does not exist, does not belong to the integration, or has been revoked

Revoke Credential

DELETE /v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id}

Permanently disables a credential. Revoked credentials cannot be used to authenticate or create sessions. This action cannot be undone.

Response

204 No Content.

Errors

Status	Error	Description
404	Not Found	Credential does not exist or does not belong to the integration

Authentication Flow

Once you have a credential, use it to obtain access tokens and create external user sessions:

1. Obtain an access token. Use the client_credentials grant type with the credential's client_id and client_secret. The returned token has the external_user_sessions:create scope.

2. Create an external user session. Use the access token as the parent token in an external_user_session grant request. Specify a service_id from the credential's allowed service list, along with the workspace_id and consumer_entity_id.

The service_id must be in the credential's allowlist. Requests for services not in the list are rejected with a 403 error.

External integration tokens are exempt from IP allowlist checks and MFA enforcement.

Permissions

All credential management endpoints require:

• Integration update permission

• API key create permission

• API key delete permission

These permissions are typically held by admin and owner roles.

Comparison with Service Accounts

Capability	Service Account	External Integration Credential
Create external user sessions	Yes, for any service	Yes, only for allowed services
Service restriction	No	Yes, scoped to a service allowlist
Integration binding	No	Yes, bound to a specific integration
IP allowlist enforcement	Exempt	Exempt
MFA enforcement	Exempt	Exempt
Secret rotation	Supported	Supported
Revocation	Supported	Supported

Use external integration credentials when you want to grant a third-party system the minimum access needed to create user sessions for specific services, without exposing full service account capabilities.