Scopes

Scopes define what your integration is allowed to do when calling the APIs. When creating a token or configuring an authorization flow, you select the scopes your integration needs. These scopes limit access to specific resources or actions, such as reading chats or updating settings. You choose scopes based on what your integration needs to do. For example, if your app only reads data, you can grant read-only scopes. To see which scopes are required for a specific API method, check the method description in the API documentation.

General rules

ro means read only
rw means read/write
rc means read/create
all rw scopes contain ro privileges
all access scopes contain my privileges
all all scopes contain access privileges and my privileges

Accounts scope types

Account scopes

Scope	Description	Role	Role type
`accounts--my:ro`	Read permission for my account	member	primary
`accounts--my:rw`	Read and modify permission for my account	member	primary
`accounts--all:ro`	Read permission for all accounts in an organization	member	primary
`accounts--all:rw`	Read and modify permission for all accounts	administrator	primary
`accounts--all:rc`	Create and read accounts (modification is denied)	member	primary

Role scopes

Scope	Description	Role	Role type
`accounts.roles--all:ro`	Read all accounts roles	member	primary

Session scopes

Scope	Description	Role	Role type
`sessions--my:ro`	Read my sessions	member	primary
`sessions--my:rw`	Read and modify my sessions	member	primary

Organization scopes

Scope	Description	Role	Role type
`organization--my:rw`	Read and modify organization settings	owner	primary

Text scope types

Agent scopes

Scope	Description	Role	Role type
`agents--my:rw`	Write permission for my profile configuration	normal	secondary
`agents--my:ro`	Read permission for my profile configuration	normal	secondary
`agents--all:rw`	Write permission for all agents profiles configuration	administrator	secondary
`agents--all:ro`	Read permission for all agents profiles configuration	normal	secondary
`accounts.roles.lc--all:rw`	Read and modify all account roles within the Text product	administrator	secondary

Access rules scopes

Scope	Description	Role	Role type
`access_rules:ro`	Read permission for auto chat scopes configuration	administrator	secondary
`access_rules:rw`	Read/write permission for auto chat scopes configuration	administrator	secondary

Bot scopes

Scope	Description	Role	Role type
`agents-bot--my:ro`	Read permission for bot agents configuration (only my bot agents)	administrator	secondary
`agents-bot--my:rw`	Read/write permission for bot agents configuration (only my bot agents)	administrator	secondary
`agents-bot--all:ro`	Read permission for bot agents configuration (all in license)	normal	secondary
`agents-bot--all:rw`	Read/write permission for bot agents configuration (all in license, delete only)	administrator	secondary

Group scopes

Scope	Description	Role	Role type
`groups--my:rw`	Write/read permission for groups I’m a member of	administrator	secondary
`groups--my:ro`	Read permission for groups I’m a member of	normal	secondary
`groups--all:rw`	Write/read permission for all groups within a license	administrator	secondary
`groups--all:ro`	Read permission for all groups within a license	normal	secondary

Chat scopes

Scope	Description	Role	Role type
`chats--all:ro`	Read permission for conversation and meta data of all license chats	administrator	secondary
`chats--access:ro`	Read permission for conversation and meta data of chats with requester access	normal	secondary
`chats--all:rw`	Read/write permission for conversation and meta data of all license chats	administrator	secondary
`chats--access:rw`	Read/write permission for conversation and meta data of chats with requester access	normal	secondary

Chats conversation data applies to:
- chat events
- chat properties
- thread properties
Chats meta data applies to:
- chat users

Customer scopes

Scope	Description	Role	Role type
`customers.ban:rw`	Permission for banning customers	normal	secondary
`customers:own`	Permission for owning and managing customer identities. It allows for acquiring a customer token (for both existing and new customers) and using it to call the Customer Chat API as a customer.	administrator	secondary
`customers:ro`	Read permission for customers	normal	secondary
`customers:rw`	Read/write permission for existing customers. It also allows for creating new customers via the Agent Chat API.	normal	secondary

Multicast scopes

Scope	Description	Role	Role type
`multicast:rw`	Permission for multicast data to agents or customers	normal	secondary

Properties scopes

Scope	Description	Role	Role type
`properties.license.value--my:rw`	Read/write permission for managing license properties (only my namespace)	administrator	secondary
`properties.license.value--all:rw`	Read/write permission for managing license properties (in all namespaces but with access only to their public properties)	administrator	secondary
`properties.group.value--my:rw`	Read/write permission for managing groups properties (only my namespace)	administrator	secondary
`properties.group.value--all:rw`	Read/write permission for managing groups properties (in all namespaces but with access only to their public properties)	administrator	secondary
`properties.configuration:rw`	Read/write permission for license/group/chat/thread/event properties configuration (for all integrations owned by my license)	administrator	secondary

Tag scopes

Scope	Description	Role	Role type
`tags--all:rw`	Read/write permission for tags configuration (all in license)	administrator	secondary
`tags--all:ro`	Read permission for tags configuration (all in license)	not assigned to any role	secondary
`tags--groups:rw`	Read/write permission for tags configuration (in my groups)	not assigned to any role	secondary
`tags--groups:ro`	Read permission for tags configuration (in my groups)	normal	secondary

Webhook scopes

Scope	Description	Role	Role type
`webhooks--my:ro`	Read permission for webhooks configuration (only my webhooks)	administrator	secondary
`webhooks--my:rw`	Read/write permission for webhooks configuration (only my webhooks)	administrator	secondary
`webhooks--all:ro`	Read permission for webhooks configuration (all in license)	administrator	secondary
`webhooks--all:rw`	Read/write permission for webhooks configuration (all in license, delete only)	administrator	secondary
`webhooks.state:ro`	Read permission for the webhook state (only my webhooks)	administrator	secondary
`webhooks.state:rw`	Read/write permission for enabling/disabling webhooks (only my webhooks)	administrator	secondary
`webhooks.configuration:rw`	Read/write permission for adding and updating the webhook configuration	administrator	secondary

Accessing chat

This chart shows every possible chats scenarios:

chats without my access and without my presence (chats -A -P)
chats with my access but without my presence (chats +A -P)
chats with my presence but without my access (chats -A +P)
chats with my access and with my presence (chats +A +P)

The table shows scopes dependency of accessing chat:

	`chats -A -P`	`chats +A -P`	`chats -A +P`	`chats +A +P`
`all`	✓	✓	✓	✓
`access`	-	✓	✓	✓
`my`	-	-	✓	✓

Accessing parts of chat

The table shows scopes dependency of accessing chat parts:

	meta data	conversation data
`chats-*:rw`	rw	rw
`chats.conversation-*:rw`	ro	rw
`chats-*:ro`	ro	ro

Getting started

Key concepts

API overview

Authentication

General rules

Accounts scope types

Account scopes

Role scopes

Session scopes

Organization scopes

Text scope types

Agent scopes

Access rules scopes

Bot scopes

Group scopes

Chat scopes

Customer scopes

Multicast scopes

Properties scopes

Tag scopes

Webhook scopes

Accessing chat

Accessing parts of chat

​General rules

​Accounts scope types

​Account scopes

​Role scopes

​Session scopes

​Organization scopes

​Text scope types

​Agent scopes

​Access rules scopes

​Bot scopes

​Group scopes

​Chat scopes

​Customer scopes

​Multicast scopes

​Properties scopes

​Tag scopes

​Webhook scopes

​Accessing chat

​Accessing parts of chat

General rules

Accounts scope types

Account scopes

Role scopes

Session scopes

Organization scopes

Text scope types

Agent scopes

Access rules scopes

Bot scopes

Group scopes

Chat scopes

Customer scopes

Multicast scopes

Properties scopes

Tag scopes

Webhook scopes

Accessing chat

Accessing parts of chat