Keys and permissions
Live and test keys, scopes, expiry and the playground.
Every request carries a key in the Authorization header:
Authorization: Bearer ak_live_…Live and test keys
| Key | Starts with | What it does |
|---|---|---|
| Live | ak_live_ | Reads and changes your workspace. |
| Test | ak_test_ | Reads your real data; every change runs as a dry run. Sends are never real. |
A key is shown once, when it is made. After that you only see its name, last four characters and permissions. Lost it? Make a new one and revoke the old one.
Permissions (scopes)
New keys can only read. Tick more when you make the key — give each integration only what it needs.
| Scope | In plain words |
|---|---|
mcp:read | Read your data |
crm:write | Create and edit contacts, tags, contact groups and custom fields |
messaging:write | Send WhatsApp messages; manage templates and quick messages |
inbox:write | Manage conversations: notes, assign, close, tags, reminders |
webhooks:write | Manage webhook endpoints |
A call without the right scope gets 403 insufficient_scope.
Expiry, IP allowlist and version
Keys expire after 90 days unless you choose otherwise. You can limit a key to your servers' IP addresses. Each key is pinned to the API version that was current when it was made (see Versions).
The playground on this site
When you are signed in and pick a key in Key ▾, this site gets a playground token from that key: it lasts 15 minutes, can do at most what the key can, and is kept in this browser tab's memory only. Your key's secret never comes to this site.
Never put keys in a browser
Keys are for servers. The API does not accept keys from arbitrary web pages. If a key leaks, revoke it at once in the app.