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.
Connecting an AI agent to the MCP server? You don’t need to create or paste an API key at all — POST /mcp also accepts OAuth tokens. Your agent walks through a consent screen, you pick the scopes, and the connection can be revoked any time from Settings → API Keys → Connected AI agents. See the MCP guide for both options.
If your workspace’s trial has expired (and no paid plan is active), API keys stop working entirely — reads included. Every /api/v1/ and /mcp request returns 403 Forbidden until the workspace is reactivated from the dashboard. Don’t build a read-only fallback for this state; there isn’t one. (The dashboard itself keeps read access, so your team can still see their data and reactivate — only key-authenticated API traffic is cut off.)

​
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.