Authentication - Communicate Developer

For workspace agent discovery and chat integrations, use the OAuth 2.0 client-credentials flow. Account management operations use a separate account credential, described below. When you create a workspace key in Communicate, save both values shown once:

Client ID — the key ID.
Client secret — the ck_ secret.

The canonical OpenAPI 3.2.1 contract describes token exchange with HTTP Basic authentication: client ID as username and client secret as password. Send these credentials when requesting a token; an access token is not required for that exchange.

Request an access token

Choose the smallest scopes the integration needs:

Scope	Permission
`agents:read`	List agents in the workspace
`chat:write`	Send chat turns to workspace agents

export COMMUNICATE_CLIENT_ID="your_key_id"
export COMMUNICATE_CLIENT_SECRET="ck_your_secret"

curl -u "$COMMUNICATE_CLIENT_ID:$COMMUNICATE_CLIENT_SECRET" \
  https://app.communicate.so/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=agents%3Aread"

The response contains a bearer token valid for one hour:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "agents:read"
}

Use the access token on API requests:

Authorization: Bearer your_access_token

Requested scopes must be a subset of the permissions selected when the key was created. Revoking or narrowing the source key takes effect immediately, including for access tokens already issued. Access tokens are resource-bound. REST tokens default to https://app.communicate.so/api/v1. To connect an MCP client, request a separate token for https://app.communicate.so/mcp as shown in Connect with MCP. REST tokens cannot call MCP, and MCP tokens cannot call REST.

Direct API keys

Existing integrations can continue using the ck_ secret directly. Its effective permissions are the key’s complete scope set.

Authorization: Bearer ck_your_key

Treat API keys as server-side secrets. Do not place them in browser code, mobile apps, public repositories, logs, or URLs.

Keys are workspace-bound. A credential can access only agents in its workspace, and revoked keys stop working immediately. Direct ck_ keys are accepted only by the REST API. MCP accepts resource-bound workspace OAuth tokens for read-only agent discovery, or explicitly MCP-bound account credentials for scoped management. Missing and invalid bearer credentials return 401 with a WWW-Authenticate challenge and a structured JSON error.

{
  "error": "Missing API key",
  "code": "api_key_missing"
}

Account management credentials

Account credentials use the ca_ prefix and authorize supported account, workspace, member, team, agent, source, learning, Grill and personal-notification management operations. A workspace OAuth token or ck_ key does not grant these account scopes. Each operation’s API reference declares its required credential and scope. Verified email/password users can obtain an account credential without a browser session using POST /account-credentials/bootstrap or the CLI bootstrap command. Use the request schema in the API reference and request only the scopes needed by your workflow. Account credentials expire within 24 hours and cannot outlive their issuer session. Every request checks current user, credential, membership, role and entitlement. Revocation, expiry and scope narrowing take effect on subsequent authorization checks. Account credentials default to the REST audience https://app.communicate.so/api/v1. To use MCP management, explicitly request "audience": "https://app.communicate.so/mcp" during bootstrap or creation. REST-bound account credentials cannot call MCP, and MCP-bound account credentials cannot call REST. Rotation preserves the existing audience. Credential creation, editing, rotation and revocation require fresh password proof and credentials:write; listing requires credentials:read. A machine caller cannot issue or rotate into broader authority or a longer lifetime. Save one-time secrets only in protected files or your secret manager. Native browser-session writes retain their Origin protection.

​Request an access token

​Direct API keys

​Account management credentials

Request an access token

Direct API keys

Account management credentials