Create an OAuth client

  Divisions and scopes: Feature coming soon.

  • OAuth > Client > Add permission

This procedure is for application providers who want their app to receive a token allowing it to make requests to the PureCloud Public API. The token represents a user’s permission for the app to access PureCloud data. It is used when the app must authorize a request to an API endpoint. See also: Create an OAuth Client in the PureCloud Developer Center.

  1. Click Admin.
  2. Under Integrations, click OAuth.
  3. Click Add client. The Client Details tab appears.

  4. Set App Name to a descriptive name of the app. This is name shown when someone authorizes this OAuth client.
  5. (Optional) Type a brief description of the app in the Description box.
  6. Next, set the duration of time until tokens created with this client expire. Accept the default duration, or enter a value between 300 and 172800 seconds. This sets the lifetime of the token to a maximum of 2 days or less.
  7. Make a selection below Grant Types. Grant Types set the way an application gets an access token. PureCloud supports the OAuth 2 authorization grant types listed below. Clicking the name of a grant type displays more information about it from the PureCloud Developer Center.

    • Client Credentials Grant: A single-step authentication process exclusively for use by non-user applications (e.g. a Windows Service or cron job). The client application provides OAuth client credentials in exchange for an access token. This authorization type is not in the context of a user and therefore will not be able to access user-specific APIs (e.g GET /ap1/v2/users/me).

      If assigning roles for PureCloud for Salesforce, see also OAuth Client Permissions for PureCloud for Salesforce.

    • Code Authorization Grant: A two-step authentication process where a user authenticates with PureCloud, then the client application is returned an authorization code. The client application provides OAuth client credentials and uses the authorization code to get an access token. The access token can then be used when making authenticated API calls. This is the most secure option and ideal for websites where API requests will be made server-side (e.g. ASP.NET or PHP) and some desktop applications where a thin client would authorize the user and pass the auth code to a back-end server to exchange for an auth token and make API requests.

    • Token Implicit Grant (Browser): A single-step authentication process where a user authenticates with PureCloud and the client application is directly returned an access token. This option provides less security for the access token than the authorization code grant, but is ideal for client-side browser applications (i.e. JavaScript) and most desktop applications (e.g. .NET WPF/WinForms or Java desktop programs).

    • SAM2 Bearer: An authentication process wherein a client application may use a Security Assertion Markup Language (SAML2) assertion to request a bearer token. See also: PureCloud single sign-on and identity provider solution.

  8. Supply parameters required by the grant type.

    • Roles: If you selected Client Credentials, click the Roles tab. This opens a list of roles to choose from. Assign a minimum set of roles to determine what your OAuth client integration can do.

      You must also associate each role with a division. Determine what divisions should be associated with roles for the Client Credential Grant. All Client Credential grant roles are scoped to the Home Division by default. Update with appropriate divisions so that the applications and systems which use those grants can access the appropriate data. If a client credential grant is supplied by a 3rd party, check with the 3rd party to understand the use of the grant and update the divisions for the roles appropriately. No other grant types are affected by access control.

    • Authorized redirect URIs (one per line): These are the URIs that authorization code is posted to, to be exchanged for an access token used later to authenticate subsequent API calls.

    • Scope: all grant types except Client Credentials have a Scope setting. Click the Scope box to display a list of scopes available to your app. As a best practice, select only the minimum scopes your app needs. For information about scopes, see OAuth Scopes in the Developer Center.

  9. Click Save. PureCloud creates a Client ID and a Client Secret (token).

Your PureCloud OAuth client is now ready to use.