API
API authentication
Create, scope, update, and revoke one-time Coop API tokens.
Send the token in the Authorization header on every public API request:
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
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-tokenslists 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:
{
"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
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.