OAuth scopes for applications overview


PureCloud’s Platform API implements and adheres to the OAuth 2 standard. OAuth allows organizations to share information without sharing user credentials. PureCloud’s OAuth scopes for applications feature authorizes an app to access information in PureCloud, 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 PureCloud will request access to PureCloud resources, and then make Platform API calls. An app may request access to information in PureCloud 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 PureCloud.

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 PureCloud 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 PureCloud—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.