Authentication
Pass the key as a bearer token:
Authorization: Bearer ck_live_a1b2c3d4_Xy9…If your HTTP client cannot set Authorization, X-Api-Key: ck_live_… is accepted instead.
A key looks like ck_<env>_<prefix>_<secret> — live on production, test elsewhere.
Only the ck_<env>_<prefix> half is stored in readable form; the secret is kept as a hash,
so a lost key cannot be recovered, only replaced.
A key is bound to one workspace. No endpoint in this API takes a workspace or tenant id — the key names it. There is no way to ask for another workspace’s data, and nothing you send needs to identify yourself beyond the key.
Scopes
Section titled “Scopes”One scope for sending. Reading is split by what it exposes, so a key that polls delivery status cannot also download attachments or read your conversations.
| Scope | Grants |
|---|---|
WHATSAPP_SEND |
POST /messages/whatsapp and /preview. Includes CATALOG_READ |
MESSAGES_READ |
the message log and single messages: text, status, your metadata |
MEDIA_READ |
attachment bytes — the files customers actually sent |
CONVERSATIONS_READ |
the thread list, with contact names and numbers |
CONVERSATIONS_WRITE |
marking inbound messages read, and the typing bubble |
CALLS_READ |
the call log |
CALLS_WRITE |
answering, declining and placing calls from your own server. Includes CALLS_READ |
CAMPAIGNS_READ |
campaigns and their recipient reports — which list every number on them |
CAMPAIGNS_WRITE |
building, starting, pausing and cancelling campaigns. Includes CAMPAIGNS_READ |
CATALOG_READ |
/templates and /numbers. Comes with any send scope |
Grant the narrowest set that does the job. The split exists so that the common case — a
backend that sends order updates and watches whether they arrived — needs only
WHATSAPP_SEND and MESSAGES_READ, and a key that leaks cannot be turned into a customer
list.
Scopes are read on every request, so narrowing or widening a key in the console takes effect on the next call — the secret does not change and your integration keeps working.
A key can never create another key. Key and webhook management is console-only, which is what stops a leaked key from extending its own reach.
Failures
Section titled “Failures”| Failure | HTTP | Code |
|---|---|---|
| no key on the request | 401 | UNAUTHORIZED |
| unknown, revoked or expired key | 401 | INVALID_API_KEY |
| key lacks the scope the route needs | 403 | FORBIDDEN |
| workspace suspended | 403 | TENANT_SUSPENDED |