Authentication - Communicate Developer

For server-to-server integrations, use the OAuth 2.0 client-credentials flow. When you create a key in Communicate, save both values shown once:

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

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. The MCP endpoint requires a short-lived OAuth access token. 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"
}

​Request an access token

​Direct API keys

Request an access token

Direct API keys