Authentication
API keys, scopes, IP allow-lists, rate limits.
Authenticate every request with an API key, sent either as a bearer token or in the X-API-Key header.
Authorization: Bearer wk_xxxxxxxxxxxxxxxx
# or
X-API-Key: wk_xxxxxxxxxxxxxxxxKeys are stored hashed, so we cannot show a key again after creation. If you lose one, revoke it and create a new one. Never put a key in browser code or a mobile app.
Scopes
Each key carries a list of scopes; an endpoint rejects keys that lack the scope it needs with 403 insufficient_scope. Grant only what an integration requires.
| Scope | Grants |
|---|---|
messages:send | Send messages (POST /messages) |
messages:read | List and fetch messages |
contacts:read | List contacts |
contacts:write | Create, update and delete contacts |
templates:read | List message templates |
campaigns:read | List campaigns and read their statistics |
campaigns:write | Reserved for campaign management |
webhooks:manage | Reserved for webhook management |
Available scopes: messages:send, messages:read, contacts:read, contacts:write, templates:read, campaigns:read, campaigns:write, webhooks:manage.
Key restrictions
- IP allow-list — optionally restrict a key to up to 20 IP addresses. Other IPs get
403 ip_not_allowed. - Expiry — optionally set an expiry date. Expired keys get
401 expired_key. - Revocation — revoked keys get
401 invalid_keyimmediately. - Plan — API access must be included in your plan, otherwise
403 api_disabled.
Rate limits
Each key has a per-minute request limit set by your plan (60 per minute if the plan does not define one). Every response includes:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute |
X-RateLimit-Remaining | Requests left in the current window |
Retry-After | Seconds to wait — only on 429 |
On 429 rate_limited, wait for Retry-After seconds and retry. Spread bulk sends out, or use campaigns for large audiences.
Check a key — GET /me
/meReturns the workspace, plan, this month’s message usage, the key’s scopes and the connected numbers.
{
"workspace": { "id": 12, "name": "Acme Retail" },
"plan": { "name": "Growth", "monthly_messages": 50000, "api_rate_limit": 300 },
"usage": { "messages_this_month": 1840 },
"scopes": ["messages:send", "messages:read"],
"numbers": [
{ "id": 3, "name": "Support", "display_phone": "+1 415-555-0100", "phone_number_id": "1098765432101", "quality_rating": "GREEN" }
]
}