Permissions (scopes)
Each key has a list of scopes. account:read (who am I, inboxes, teams, agents, labels) is implicit. There is no
"full access" scope.
| Scope | Allows | Notes |
|---|---|---|
contacts:read |
List and read contacts, companies and contact notes | E-mail, phone and identifier masked |
contacts:pii |
See personal data unmasked (also inside messages) | For AI assistants, prefer leaving it off |
contacts:write |
Create and change contacts, notes and labels | Never deletes contacts |
conversations:read |
Conversation data: status, inbox, assignee, team, labels, waiting time | No message text |
messages:read |
Message text of the conversations the key can see | Private notes only on request |
conversations:write |
Status, assignee, team, priority, labels, private notes | Never talks to the customer |
messages:send |
Send a message to the customer of an existing conversation | Needs approval by default |
crm:read |
Pipelines, deals, tasks, timeline, funnel report | Business plan |
crm:write |
Create, change, move, win, lose, reopen deals; tasks | Business plan |
knowledge:read |
Search the assistants' knowledge, approved FAQs | |
knowledge:write |
Suggest FAQs (kept pending for review) | |
reports:read |
Period reports and agent workload | Administrators only |
webhooks:manage |
Create, list, change and remove the account's webhooks | Administrators only |
Rules
- Scopes are checked on every request: when the plan changes or the role of a personal key's user is reduced, the key loses that access at once, without editing it.
- Without the route's scope:
403 insufficient_scopewithrequired_scopes. In MCP, the tool does not even appear intools/list. - Personal keys never do more than the person: an agent only sees the conversations of their inboxes and teams.
- The optional inbox restriction limits conversations, messages, the queue and sending; contacts stay account-wide.
Templates
| Template | Kind | Scopes |
|---|---|---|
| AI assistant (read only) | personal | contacts:read, conversations:read, messages:read, crm:read, knowledge:read, reports:read |
| AI assistant (read and act) | personal | the above + writes and messages:send with approval |
| ERP / management system | service | contacts:read, contacts:pii, contacts:write, crm:read, crm:write, webhooks:manage |
| Automation (n8n, Make, Zapier) | service | contacts:read, contacts:write, conversations:read, conversations:write, webhooks:manage |