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

ScopeAllows
contacts:readSearch and list accessible Contacts
contacts:addresses:readInclude exact Contact, recipient, and sender addresses in Contact and conversation responses
conversations:readResolve Contact conversations and list recent conversations
messages:readRead paginated conversation messages
messages:sendSend 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

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.