Getting started
Scopes
What each permission unlocks, and which routes a key can never reach.
Each key carries a list of scopes. A request to a route whose scope the key lacks is refused with 403 MISSING_SCOPE, and the response names the scope that was missing.
| Scope | Unlocks |
|---|---|
chats:read | List conversations, contacts, messages, tags and media. |
chats:write | Resolve, favorite, assign and annotate conversations; add or remove a tag on a conversation; update a contact. |
messages:send | Send and edit messages, start conversations, upload media. |
tags:write | Create, rename and delete tags. |
groups:read | Group metadata, invite codes and profile pictures. |
groups:write | Create groups, manage participants, invite people, edit subject, description and picture. |
A key created without choosing scopes is read-only: chats:read and groups:read. The power to send must be granted explicitly.
Routes open to any key
GET /health, GET /integrations and the MCP endpoint need no specific scope. Inside MCP, each tool call is checked against the scope of the route it uses.
What a key can never do
Connecting or disconnecting a number, reading QR codes, syncing history, billing and account settings are dashboard-only. Any route not listed in this reference answers 403 ROUTE_NOT_PUBLIC, even for a key with every scope.