Scopes
Every scope the API offers, what each one unlocks, and the 403 you get when a token is missing one.
Scopes are granted when a user installs your app. The API checks the granted scope set on every request. If your app's scopes change, the change takes effect on the very next API call. You do not need to refresh the access token or reinstall.
All scopes
| Scope | Description |
|---|---|
workspaces.read | List workspaces and their settings. |
workspaces.write | Create, update and delete workspaces. |
devices.read | List paired devices and their statuses. |
devices.write | Pair, assign and remove devices. |
contacts.read | List contacts and view their details. |
contacts.write | Create, update and delete contacts. |
messages.read | View inbound and outbound message history. |
messages.write | Send outbound messages on behalf of the user. |
messages.send | Send outbound messages on behalf of the user (legacy alias of messages.write). |
automations.read | List workflows and view executions. |
automations.write | Create, update, activate and delete workflows, and add contacts to them or remove them. |
conversations.read | List conversations and read their messages. |
conversations.write | Mark conversations read or unread, star and archive them. |
calls.read | Readiness, lines, call routing, ringing calls, call history, and following a call. |
calls.write | Place calls and missed calls, end them, decline ringing calls, save call routing. |
groups.read | List iMessage group chats. |
groups.write | Create, rename and leave group chats, manage participants and CRM bridging, send to them. |
lead_forms.read | List lead forms and read their submissions. |
lead_forms.write | Create, update and delete lead forms. |
opportunities.read | List pipelines, stages and opportunities. |
opportunities.write | Create, update, move, close and delete opportunities. |
tasks.read | List tasks and view their details. |
tasks.write | Create, update, complete, reopen and delete tasks. |
subaccount_admins.read | List subaccount admins and the workspaces they can access. |
subaccount_admins.write | Invite, update, deactivate and delete subaccount admins. |
ai_agents.read | List AI agents and read their configuration. |
ai_agents.write | Create, configure, activate, pause, duplicate and delete AI agents. |
Choosing scopes
Request the smallest set your app needs. A read scope covers the GET routes of its area. A write scope covers the routes that create, change or delete. Each endpoint page in the reference names the scope it requires.
Scope enforcement
Every endpoint declares the scope it requires. If your token is missing it, the response is 403 Forbidden with a message that lists what the integration was granted against what the route needs:
{
"success": false,
"message": "Missing scope(s): contacts.write. This integration was granted: contacts.read"
}A 403 is not fixed by refreshing the token. Reinstall the app with the missing scope included, or ask Blue Reacher to add it to the app's registration. The next request after the change is checked against the new set.
Scopes on the token
The granted scopes are returned with every token response and in the scopes claim of the access token. GET /v1/integration/me returns them too, which makes it a quick way to check what an installation can do. See Token format.