> ## Documentation Index
> Fetch the complete documentation index at: https://developer.communicate.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Choose scoped account credentials, workspace OAuth tokens, or workspace API keys.

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](https://app.communicate.so/api/v1/openapi.json)
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 |

```bash theme={null}
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:

```json theme={null}
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "agents:read"
}
```

Use the access token on API requests:

```http theme={null}
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](/docs/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.

```http theme={null}
Authorization: Bearer ck_your_key
```

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

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.

```json theme={null}
{
  "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](/docs/cli#authenticate-without-a-browser). 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.