Skip to main content

​
API keys

Every request to /api/v1/ authenticates with a workspace API key in the Authorization header:
Keys are created and managed in Settings → API Keys. Each key is scoped to exactly one workspace — a key issued for workspace A can never read or write workspace B’s data, regardless of what other workspaces its creator belongs to. A complete authenticated request looks like this:
A missing, malformed, or revoked key returns 401 Unauthorized with the standard error envelope. A valid key that lacks the scope an endpoint requires returns 403 Forbidden.
If your workspace’s trial has expired (and no paid plan is active), API keys become read-only — GET requests keep working, but writes (POST/PATCH/DELETE) return 403 Forbidden. Reactivate the workspace from the dashboard to restore write access.

​
Scopes

A key only has the permissions explicitly granted to it. Request only what you need.
ticket.manage deliberately covers both day-to-day ticket work and pipeline/stage configuration — there’s no separate “admin” scope for tickets. The same reasoning applies to chat.assign, which covers both editing a conversation’s status/priority/tags and reassigning it to a different teammate or inbox.

​
What’s not yet in scope

WhatsApp Flows are read-only via the API today — creating, uploading, publishing, or deprecating a Flow has to happen in the dashboard. Ticket SLA policies aren’t exposed via the API at all yet. Both are natural candidates for a future release. The scopes table above is the complete list of scopes any /api/v1/ endpoint actually checks. Workspace membership manages a broader internal permission vocabulary (billing, team, WhatsApp account connection, contact notes) — those permissions govern the dashboard only and aren’t exposed as API key scopes today, so granting them to a key has no effect on /api/v1/ access.

​
Escalation guard

A workspace member can never mint a key with more access than they hold themselves — if you don’t have workspace.manage_billing yourself, you can’t create a key that has it either.