Scopes
A connection can do only what its scopes allow. This is what each one allows, who can give it, and what no scope allows.
This page is for the developer deciding what a connection needs to reach, and for the manager in your organisation who gives it that access.
It lists every scope, who can give each one, and what a connection cannot do whatever scopes it holds.
The scopes
| Scope | Allows |
|---|---|
conversations:read | list conversations, and read one, its transcript and its facts |
summaries:read | read a conversation's summary |
cases:read | list cases and read one |
cases:write | create a case, and start a conversation in one |
documents:write | send a document in a case to be translated |
documents:read | read a sent document and its translation |
users:read | list people and invitations, and read one |
users:write | add, change and remove people, withdraw an invitation, and set a person's group |
groups:read | list groups and the permissions they hold |
groups:write | add, change and delete groups, and set their permissions |
webhooks:manage | add, change and remove the connection's webhooks |
GET /me needs no particular scope. Any other call that needs a scope the connection does not hold answers 403 scope_missing.
A write scope does not include its read scope. A connection that creates cases and reads them back needs both cases:write and cases:read.
Who can give a scope
Scopes are chosen on the Integrations page when a connection is made, and you can change them there later. The person choosing must hold Manage integrations, and for each scope the permission it reads or writes:
| Scope | Permission the person must hold |
|---|---|
conversations:read, summaries:read | Read conversations |
cases:read, cases:write, documents:write, documents:read | access to cases |
users:read, users:write | Manage users |
groups:read, groups:write | Manage groups |
webhooks:manage | Manage integrations only |
If somebody without a scope's permission saves the connection, a scope it already holds stays. They cannot add it.
A change of scopes applies from the next call, to every key of the connection.
What no scope allows
- Starting a conversation without a person.
cases:writeanswers an address, and a signed-in member of your organisation opens it to start the conversation. - Sending a password reset, removing an authenticator, or removing passkeys.
- Erasing a person.
users:writeremoves a person from your organisation, and their account remains. - Giving away the management permissions. A connection cannot give a group Manage users, Manage billing, Manage integrations or Manage groups, or put a person in a group that holds one of them. These answer 403
permission_not_grantable. - Reaching another organisation. Nothing of another organisation can be read or changed. These answer 404
not_found.
Choosing scopes
Give a connection only the scopes its job needs. These are the usual sets:
| Use | Scopes |
|---|---|
| Copy summaries into a case management system | conversations:read, summaries:read, webhooks:manage |
| Open a case from another system and start a conversation in it | cases:read, cases:write |
| Send letters to be translated | cases:read, documents:write, documents:read, webhooks:manage |
| Provision accounts from an identity provider | users:read, users:write, groups:read, groups:write |