OAuth scopes for applications overview

Genesys Cloud’s Platform API implements and adheres to the OAuth 2 standard. OAuth allows organizations to share information without sharing user credentials. Genesys Cloud’s OAuth scopes for applications feature authorizes an app to access information in Genesys Cloud, without giving the app login credentials or allowing it to access every resource that its users are permitted to. For additional background information, see: Authorization and Digging deeper in the Developer Center.

A custom app developed for Genesys Cloud will request access to Genesys Cloud resources, and then make Platform API calls. An app may request access to information in Genesys Cloud that its user can get to, but it should not be allowed to perform every operation that the permissions of its current user might allow.

Prior to the implementation of OAuth scopes for applications, any permissions assigned to the user defined the resources an application could call.

For example, an app whose current user had the Directory > User > Add permission could potentially ask the API to create a new user, because its user could do that.

To overcome this vulnerability, administrators assign scopes to an app, restricting its access to operations and data.

Scopes define what an app can do, and prevent it from doing something unintended (out of scope). To function within an org, an app must be authorized by an administrator to have specific scopes. In addition, users of the app must have permissions to access corresponding resources in Genesys Cloud.

Using OAuth scopes, an application whose user has permission to create users could not, unless a scope allowing that action is specifically granted to the app by a person with the Oauth > Client > Authorize permission.

The person who authorizes scopes is usually a Genesys Cloud administrator who understands the implications of data access. Since scopes are org-specific, administrators can limit what each app can do in their org.

OAuth scopes require the application to authorize each API call:

  • The user must have permission to access and/or update Genesys Cloud—the Directory > User permission in this example.
  • The app must be assigned a scope allowing it to make the API call. For this example, the users scope would allow the app to read and write users.

With these corresponding permissions and scopes, the app could create users. In this case, the app could POST to the /api/v2/users endpoint. Without the required user permission and scope, that api call would not succeed. An app is governed by the intersection of its user permissions and scopes. It cannot do anything that its user lacks permission to do, nor can it make any API calls that are out of scope for the org.