Scopes are Genesys-defined names that categorize endpoints in the Genesys Cloud Public API. When an app is authorized to have a specific scope, it can only access endpoints in the API that require that scope. An application cannot call an endpoint that requires a scope it does not have.

Every API call requires a scope, which can be read-only or read-write. A scope with the :readonly suffix is read-only. A scope with no suffix permits read-write operations.

Consider for example, two scopes which allow access to Genesys Cloud users. To grant an app access to user-related endpoints, an administrator would assign one of the following scopes to the app, based on whether the administrator wants the app to be able to modify user data or not.

Scope Name users users:readonly

Description

The users scope will allow an app to read and modify data about Genesys Cloud users.

The app can use GET, POST, PUT, PATCH, and DELETE methods to call user-relatd API endpoints.

The users:readonly scope only lets an app read user data from Genesys Cloud.

Read-only scopes use the GET method, except when POST must be used to submit data to the API call for analytics data or searches.

In those cases, the app is not modifying data, just getting data back from a POST. The overall scenario is still read-only, even if information must be sent to obtain response data.

Genesys Cloud supports many additional scopes, such as scopes for groups, voicemail, architect, stations, search, and so on. Most scopes are available with or without the :readonly suffix. For the complete list of scopes, see Scopes in the Genesys Cloud Developer Center.

Note: An app can call an API endpoint if it has a scope required by the endpoint, only when it is being used by someone who has permissions to access or modify that data. Scopes alone do not authorize access. The app’s current user must have permissions permitting the operation performed by the API call. Both scopes and permissions are required.