Authentication

Use scoped OAuth access tokens or workspace API keys.

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"
}