Scopes

A scope is a whole feature area, not a verb. Granting conversations allows every conversation operation — read, create, update, hold, resolve, delete — because an integration that can read conversations but not resolve them is usually just an integration that will be granted the second half next week.

Choose scopes the other way round instead: grant the areas an integration genuinely touches, and leave the rest off. A credential that only syncs customers into a data warehouse should hold customers and nothing else.

The catalog

Scope	Unlocks
`conversations`	List, create, update, hold, resolve and delete conversations; read the queue counts; list inboxes; read and write conversation custom attributes
`messages`	Read a conversation's messages; send text, media, notes and WhatsApp templates; delete a message; list WhatsApp templates
`customers`	Read, create, update, search and delete customers; list a customer's contacts
`customer_objects`	Read the object types and manage their records — deals, service calls, tasks and your own
`analytics`	Read dashboards and run their graphs
`studio`	Read flows, their blocks and each block's settings
`ai_world`	Read every AI capability and switch one on or off
`knowledge_base`	Manage knowledge bases, their sources and the indexed chunks
`quick_replies`	Read, create, update and delete saved replies
`forms`	Read forms and their submissions; delete a form
`documents_signature`	Read documents, upload a PDF, create and revoke signing links
`account`	Read and update the account's general and invoicing details
`business_hours`	Manage schedules; read holiday calendars
`conversation_attributes`	Read the conversation-attribute schema
`agents_teams`	Manage agents, AI agents and teams; read roles
`audit_log`	Read the account's audit trail
`billing`	Read credit balances, the usage price list, transactions and invoices
`files`	List files with their storage usage; delete files
`profile`	Read and update any agent's display name, timezone, picture and notification settings
`notifications`	Read an agent's notification feed and unread count
`sso`	Create single-use links that sign a chosen agent into the console

The four that deserve a second thought

agents_teams can spend money. Creating a human or AI agent takes a seat, and a seat the plan does not have free is a real charge on the card. Grant this only to an integration that genuinely provisions people, and read the warning on Create a human agent.

documents_signature can spend credits. Every signing link costs. The endpoint is safe to retry — a repeat for the same document and contact returns the existing link and charges nothing — but a loop that creates links for a list of contacts spends real money.

profile reaches every agent in the account, addressed by id in the path. It is the right scope for syncing display names or timezones from an HR system, and the wrong one for almost anything else.

sso grants nothing on its own. See below.

Scopes that carry extra configuration

`sso`

Ticking the scope is step one of two. The credential must also name:

the agents it may sign in as — a multi-select in Settings → API. An empty list means the credential can impersonate nobody, which is the safe default when somebody ticks the scope and saves.
the origins allowed to embed the resulting session in an iframe, if you plan to embed it. As many as you need, one per line, scheme and host only:
```
https://app.example.com
https://portal.example.co.il
https://crm.example.com:8443
```

Removing an agent from that list invalidates every SSO link already issued for them. See SSO login.

Changing scopes later

Scopes are editable on an existing credential — that is deliberate, so an integration that grows a feature does not force you to rotate a secret your client has already deployed.

The client id and the secret never change. Everything else does:

Settings → API, press Edit on the credential.
Tick or untick scopes; adjust the SSO agents and origins.
Save.

Editing a credential invalidates its outstanding access tokens. The next call answers 401 invalid_token, and the client fetches a new token carrying the new scopes. That is why the client sketch in Authentication retries once on a 401 — with that in place, a scope change is invisible to a running integration.

When a scope is missing

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential does not hold the 'conversations' scope. Edit the credential in Settings → API to grant it.",
    "details": {
      "required_scope": ["conversations"],
      "granted_scopes": ["customers", "billing"]
    },
    "request_id": "req_5f2a91c0e8b74d3a9c1e"
  }
}

The error names what was needed and what you hold, so it is usually self-diagnosing. GET /v1/oauth/introspect answers the same question for a token you already have.

Scopes are not the only gate

Two other things can refuse an otherwise well-scoped request, and it is worth knowing which is which:

402 plan_limit_exceeded — the account's plan does not include the feature, or a ceiling is full. GET /v1/billing/plan lists every limit and feature flag.
403 feature_disabled — an account-level switch is off. The knowledge base endpoints answer this when the Knowledge Base capability is switched off in AI World, so you can tell "turned off" from "nothing indexed yet".

The catalog​

The four that deserve a second thought​

Scopes that carry extra configuration​

sso​

Changing scopes later​

When a scope is missing​

Scopes are not the only gate​