Scopes

The scope registry a key draws from — thirteen read/write pairs spanning every area of the API — and the 403 a request missing one of them returns.

Requires API access to be enabled for your workspace

A key carries a subset of the scope registry, chosen at creation and immutable afterwards. Every endpoint declares the scope it requires — it is shown on each endpoint's reference page — and the check runs per request.

The registry

Scope	Grants
`chatbots:read`	Read chatbots, settings, actions, action runs, business hours
`chatbots:write`	Create/update/delete chatbots and their config
`knowledge:read`	Read sources, chunks, content
`knowledge:write`	Add/edit/delete sources, crawl, reindex
`conversations:read`	Read conversations, messages, notes, CSV export
`conversations:write`	Reply, resolve, assign, notes, bulk status
`leads:read`	Read and export leads
`leads:write`	Update and delete leads
`channels:read`	Read omnichannel connections
`channels:write`	Connect, toggle, disconnect channels
`analytics:read`	Analytics summary and topic clustering
`team:read`	Read members and invites
`team:write`	Invite, change roles/status, remove, revoke
`workspace:read`	Workspace settings, webhook config, deliveries
`workspace:write`	Change settings, wire webhooks, resend deliveries
`reseller:read`	Read reseller clients and white-label config
`reseller:write`	Provision clients, allocate credits, white-label

Two details worth noting:

*Webhook configuration rides the `workspace: scopes** — there is no separate webhooks:*` pair.
*`reseller: is special**: granting it to a key requires **organization ownership**, and at request time the key must live on the org owner's own (primary) workspace. Any other workspace gets a 403`, even with the scope present.

Missing a scope

Calling an endpoint whose scope your key lacks returns a 403 that names the missing scope:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope: conversations:write."
  }
}

This is distinct from the access-gate 403 (API access is not enabled for this workspace.) — a scope error means the workspace's access is fine and only this key is under-scoped.

Choosing scopes

Grant the least you need, per integration:

A read-only dashboard or BI sync: the :read scopes it displays — nothing else.
A CRM lead sync: leads:read (+ leads:write if it assigns owners).
A support tool that replies: conversations:read + conversations:write.
Knowledge automation (docs pipeline → chatbot): knowledge:write alone — it does not need chatbots:write to manage sources.

Because scopes are immutable, changing an integration's reach means issuing a new key with the right set and revoking the old one — which also gives you a clean audit boundary between the two configurations.

Where to go next

Last updated 11 August 2026