Amigo is now Concurrence
Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
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
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
post/v1/{workspace_id}/external-integrations/{integration_id}/credentials
POST /v1/{workspace_id}/external-integrations/{integration_id}/credentials HTTP/1.1
Host: platform.api-us.concurrence.com
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-01-01T00:00:00.000Z"
}
{
  "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-01-01T00:00:00.000Z",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "rotated_at": "2026-01-01T00:00:00.000Z",
    "revoked_at": "2026-01-01T00:00:00.000Z"
  },
  "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
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
get/v1/{workspace_id}/external-integrations/{integration_id}/credentials
GET /v1/{workspace_id}/external-integrations/{integration_id}/credentials HTTP/1.1
Host: platform.api-us.concurrence.com
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-01-01T00:00:00.000Z",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "rotated_at": "2026-01-01T00:00:00.000Z",
    "revoked_at": "2026-01-01T00:00:00.000Z"
  }
]

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
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
post/v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id}/rotate
POST /v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id}/rotate HTTP/1.1
Host: platform.api-us.concurrence.com
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-01-01T00:00:00.000Z",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "rotated_at": "2026-01-01T00:00:00.000Z",
    "revoked_at": "2026-01-01T00:00:00.000Z"
  },
  "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
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
delete/v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id}
DELETE /v1/{workspace_id}/external-integrations/{integration_id}/credentials/{credential_id} HTTP/1.1
Host: platform.api-us.concurrence.com
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.

PreviousReview Queue
NextExternal Principals

Last updated

Was this helpful?