Skip to main content
Scopes define which resources a token can access and which actions it can perform. Each API method lists its required scopes. Some methods also describe conditional scopes that apply only when you use a specific parameter or act on resources outside your usual access.

How scope names work

Most of the scope names combine a resource, a resource-reach modifier, and an access modifier:
For example, tags--groups:ro grants read access to tags available in teams you belong to.

Resource-reach modifiers

The part after -- defines which instances of a resource the scope covers. Not every scope family supports every resource-reach modifier. Check the scope catalog and the API method description before selecting a scope.

Access modifiers

The part after : defines the permitted actions. Some scope names, such as reports_read or customers:own, do not use this structure. Treat these as exact scope names and do not infer permissions from similar suffixes.
In the catalog, * is a wildcard that represents the access modifiers listed in the Access and assigned role column. For example, chats--access:* represents chats--access:ro and chats--access:rw.

How roles affect scope availability

Which scopes you can access depends on two roles: your Global Accounts role for organization management and your Text role for Text features. Global Accounts and Text roles are assigned independently. For example, you can be a Global Accounts member and a Text administrator. The scopes you can access also depend on the token type, OAuth client configuration, and your current permissions.

Scope catalog

The catalog groups scopes by resource. When a row uses *, combine the scope pattern with one of the access modifiers listed in that row.
Roles in Global Accounts and organization are Global Accounts roles unless a row identifies a Text role. Roles in all other sections are Text roles.

Global Accounts and organization

Agents and bots

Chats and messaging

Customers

Configuration

Reports