> ## 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

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

```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. 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.

```json theme={null}
{
  "error": "Missing API key",
  "code": "api_key_missing"
}
```