Authentication & permissions
API keys
Section titled “API keys”- Format:
ws_live_+ 40 hexadecimal characters. - A key belongs to the workspace (not a person) and is passed as a
header:
Authorization: Bearer ws_live_…. - Shown only once at creation; we only store a hash.
- Revocable anytime from the dashboard: immediate effect on the API and the MCP.
Scopes
Section titled “Scopes”Every key carries precise permissions, chosen at creation:
| Scope | Grants access to |
|---|---|
leads:read / leads:write |
Read leads / update status & tags |
conversations:read |
Inbox + message history |
lists:read / lists:write |
List / create lists, import contacts |
campaigns:read / campaigns:write |
List / pause & resume |
messages:send |
Send messages (anti-ban enforced) |
bookings:read |
Booked meetings |
groups:read |
Managed WhatsApp groups |
webhooks:manage |
Create / delete / test webhooks |
A key without the right scope gets 403 insufficient_scope. Grant each
integration the minimum it needs.
Rate limits
Section titled “Rate limits”Requests are limited per workspace per minute according to your plan
(60 to 1,000 req/min). Every response carries
X-RateLimit-Limit / X-RateLimit-Remaining; when exceeded:
429 rate_limited + Retry-After.
Message sends additionally have their own daily budget per WhatsApp
number (X-Quota-*): see anti-ban.
Best practices
Section titled “Best practices”- Store the key in a secrets manager, never in code.
- One key per integration (CRM, Zapier, scripts…): revoking one doesn’t break the others.
- Rotate if you suspect a leak: create the new one, switch, revoke the old.