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

Create Credential

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

Create External Integration Credential

post

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

Body

application/json

service_idsstring · uuid[] · min: 1 · max: 100Required

namestring · min: 1 · max: 256 · nullableOptional

expires_atstring · date-time · nullableOptional

Responses

201

Successful Response

application/json

client_secretstringRequired

422

Validation Error

application/json

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

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/external-integrations/{integration_id}/credentials HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 110

{
  "service_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "name": "text",
  "expires_at": "2026-07-10T21:26:19.783Z"
}

{
  "credential": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "integration_id": "123e4567-e89b-12d3-a456-426614174000",
    "client_id": "text",
    "service_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "name": "text",
    "is_active": true,
    "expires_at": "2026-07-10T21:26:19.783Z",
    "created_at": "2026-07-10T21:26:19.783Z",
    "updated_at": "2026-07-10T21:26:19.783Z",
    "rotated_at": "2026-07-10T21:26:19.783Z",
    "revoked_at": "2026-07-10T21:26:19.783Z"
  },
  "client_secret": "text"
}

List Credentials

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

List External Integration Credentials

get

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

client_idstringRequired

service_idsstring · uuid[]Required

namestring · nullableOptional

is_activebooleanRequired

expires_atstring · date-time · nullableOptional

created_atstring · date-time · nullableOptional

updated_atstring · date-time · nullableOptional

rotated_atstring · date-time · nullableOptional

revoked_atstring · date-time · nullableOptional

422

Validation Error

application/json

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

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/external-integrations/{integration_id}/credentials HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "integration_id": "123e4567-e89b-12d3-a456-426614174000",
    "client_id": "text",
    "service_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "name": "text",
    "is_active": true,
    "expires_at": "2026-07-10T21:26:19.783Z",
    "created_at": "2026-07-10T21:26:19.783Z",
    "updated_at": "2026-07-10T21:26:19.783Z",
    "rotated_at": "2026-07-10T21:26:19.783Z",
    "revoked_at": "2026-07-10T21:26:19.783Z"
  }
]

Rotate Credential

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

Rotate External Integration Credential

post

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

credential_idstring · uuidRequired

Responses

200

Successful Response

application/json

client_secretstringRequired

422

Validation Error

application/json

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

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id}/rotate HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "credential": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "integration_id": "123e4567-e89b-12d3-a456-426614174000",
    "client_id": "text",
    "service_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "name": "text",
    "is_active": true,
    "expires_at": "2026-07-10T21:26:19.783Z",
    "created_at": "2026-07-10T21:26:19.783Z",
    "updated_at": "2026-07-10T21:26:19.783Z",
    "rotated_at": "2026-07-10T21:26:19.783Z",
    "revoked_at": "2026-07-10T21:26:19.783Z"
  },
  "client_secret": "text"
}

Revoke Credential

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

Revoke External Integration Credential

delete

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

credential_idstring · uuidRequired

Responses

204

Successful Response

No content

422

Validation Error

application/json

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

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

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, external_subject_key, and optional 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.

If the resulting external-user session will call customer APIs that require per-user token exchange, include a verified external_subject_key when creating the session and bind it into the Platform Integration auth config. See External User Subject-Key Binding.

Permissions

All credential management endpoints require:

• External integration update permission (ExternalIntegration.update)
• API key create permission
• API key delete permission

These endpoints also require an admin or owner role - the role check is enforced at the route, in addition to the permission checks.

Comparison with Service Accounts

Capability	Service Account	External Integration Credential
Create external user sessions	No	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

External integration credentials are the only credential type that can create external user sessions - the parent token in an external_user_session grant must be an external integration principal, and requests with any other parent token type are rejected with a 403 error. Use them to grant a third-party system the minimum access needed to create user sessions for specific services, without exposing broader service account capabilities.