# API authentication

> Create, scope, update, and revoke one-time Coop API tokens.


Send the token in the `Authorization` header on every public API request:

```http
Authorization: Bearer coop_live_<public_id>_<secret>
```

Coop shows the complete token only once. Store it in your server's secret manager. Do not put it in browser code, source control, logs, query strings, or screenshots. Coop stores an Argon2id verifier, not the plaintext token.

## Scopes

| Scope | Allows |
| --- | --- |
| `contacts:read` | Search and list accessible Contacts |
| `contacts:addresses:read` | Include exact Contact, recipient, and sender addresses in Contact and conversation responses |
| `conversations:read` | Resolve Contact conversations and list recent conversations |
| `messages:read` | Read paginated conversation messages |
| `messages:send` | Send a text message to an accessible conversation, or to one new recipient when the token setting allows it |

A request must pass both checks: the token must have the route scope, and the global team policy must allow the target. Owners can change team access without recreating tokens. The optional arbitrary-recipient setting is a separate capability for starting a new direct conversation.

`contacts:addresses:read` extends `contacts:read` and cannot be granted without it.

## Token management

Only an Organization Owner can manage tokens. Open **Settings → API** in the dashboard to provision, update, and revoke tokens. The dashboard recommends a 90-day expiry and shows each complete token only once. **Allow new recipients** is off by default and can be changed separately for each active token.

The same operations are available through the dashboard management endpoints below. They use the Owner's Clerk session token, the dashboard Origin header, and the Organization ID in the path. They do not accept a Coop API token.

### Create

```http
POST /v1/dashboard/organizations/{organization_id}/api-tokens
Content-Type: application/json

{
  "name": "CRM integration",
  "scopes": [
    "contacts:read",
    "contacts:addresses:read",
    "conversations:read",
    "messages:read",
    "messages:send"
  ],
  "allow_arbitrary_recipients": false,
  "expires_at": "2027-01-01T00:00:00Z"
}
```

The `201 Created` response contains token metadata and a top-level `secret`. Copy the secret before closing the response. `expires_at` is optional and must be in the future. `allow_arbitrary_recipients` defaults to `false` when omitted and can be `true` only when the token has `messages:send`.

### Read

- `GET /v1/dashboard/organizations/{organization_id}/api-tokens` lists token metadata.
- `GET /v1/dashboard/organizations/{organization_id}/api-tokens/{token_id}` returns one token's metadata.

Read responses never contain the secret or its verifier. Metadata includes status, scopes, `allow_arbitrary_recipients`, expiry, last use, request count, and resource version.

### Update

`PATCH /v1/dashboard/organizations/{organization_id}/api-tokens/{token_id}` replaces the name, scopes, arbitrary-recipient setting, and optional expiry. Supply the current version:

```json
{
  "name": "CRM production",
  "scopes": ["contacts:read", "contacts:addresses:read", "conversations:read", "messages:read", "messages:send"],
  "allow_arbitrary_recipients": true,
  "expires_at": null,
  "expected_version": 3
}
```

A stale version returns `409 Conflict` and changes nothing.

### Revoke

```http
DELETE /v1/dashboard/organizations/{organization_id}/api-tokens/{token_id}?expected_version=4
```

Revocation is immediate and permanent. To rotate safely, create the replacement token, update the integration, verify it, then revoke the old token.

