Create an OAuth client


OAuth clients allow you to make requests to the Platform API or to authenticate against Genesys Cloud, or to sync entities between Genesys Cloud and third-party systems.

Prerequisites
  • 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 Genesys Cloud Platform API. The token represents a user’s permission for the app to access Genesys Cloud data. It is used when the app must authorize a request to an API endpoint. To see a list of Genesys Cloud Platform APIs, see the API resources in the Genesys Cloud 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. Genesys Cloud supports the OAuth 2 authorization grant types listed below. Clicking the name of a grant type displays more information about it from the Genesys Cloud 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 /v2/users/me).

      If assigning roles for Genesys Cloud for Salesforce, see also OAuth client permissions for Genesys Cloud for Salesforce.

    • Code Authorization Grant: A two-step authentication process where a user authenticates with Genesys Cloud, 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.

    • Implicit Grant (Browser): A single-step authentication process where a user authenticates with Genesys Cloud 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).

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

      Note: A single Code Authorization or Implicit grant type can be used in all regions.
  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.

      Note: To grant roles to an OAuth client, you must have those roles assigned to your profile.

      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, up to 125): 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. Genesys Cloud creates a Client ID and a Client Secret (token).

Your Genesys Cloud OAuth client is now ready to use.

Prerequisites
  • OAuth > Client > Add permission

If either situation applies, create an OAuth client for Genesys Cloud Embeddable Framework:

  • You are implementing a public deployment.
  • You are implementing a private deployment that accesses the getAuthToken method in your framework.js file. For more information, see User.getAuthToken in the Developer Center.

An OAuth client generates a Client ID that developers can use for the clientIds in the framework.js file. For more information, see clientIds in the Developer Center.

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

    Client Details tab for OAuth client

  4. Set App Name to a descriptive name of the app.

    App Name is the name shown when someone authorizes this OAuth client. For more information, see Authorize an OAuth client.

  5. (Optional) Type a brief description of the app in the Description box.
  6. 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 duration sets the lifetime of the token to a maximum of two days or less.

    Tip: Genesys recommends that you set the token duration to 18 hours (64800 seconds). This duration generally causes the token to expire outside of an agent’s normal workday.

  7. Under Grant Types, select Implicit Grant (Browser).

    For more information, see Authorization and Grant – Implicit in the Developer Center.

  8. Under Authorized redirect URIs, add https://apps.mypurecloud.com/crm/index.html.

    Notes:
    • If you set dedicatedLoginWindow to true in your framework.js file, also add https://apps.mypurecloud.com/crm/authWindow.html under Authorized redirect URIs. For more information, see dedicatedLoginWindow under settings in the Developer Center.
    • After Genesys publishes your public deployment, Genesys will provide you with a new URI to use.
  9. Under Scope, add all required scopes. You can also add additional scopes.

    For a list of required scopes, see Administrator requirements for the Genesys Cloud embedded clients. For information about scopes, see OAuth Scopes in the Developer Center.

  10. Click Save.

    Genesys Cloud creates a Client ID and a Client Secret.

  11. Give the developers the Client ID.

    The developers must add the Client ID to clientIds in the framework.js file. For more information, see clientIds in the Developer Center.

For more information about the integration, see About Genesys Cloud Embeddable Framework.

Prerequisites
  • OAuth > Client > Add permission
  • SCIM Integration role assigned to your user

    If SCIM Integration does not appear, restore default roles to your Genesys Cloud organization. Use API Explorer to make an API call to POST /api/v2/authorization/roles/default. For more information, see Developer tools quick start in the Developer Center. To access API Explorer, go to https://developer.mypurecloud.com/developer-tools/#/api-explorer.

To use Genesys Cloud SCIM (Identity Management), create a Genesys Cloud OAuth client. The OAuth client generates a Client ID and Client Secret that you add to your identity management system.

  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.

    App Name is the name shown when someone authorizes this OAuth client. For more information, see Authorize an OAuth client.

  5. (Optional) Type a brief description of the app in the Description box.
  6. Set Token Duration

    Token Duration is the duration of time until tokens created with this client expire. Accept the default duration of 86,400, or enter a value between 300 and 38,880,000 seconds. This sets the lifetime of the token to a maximum of 450 days.

    Note: You can only set the maximum to 38,880,000 seconds if you use the SCIM Integration role or a custom role that has the exact same permissions.

  7. Under Grant Types, select Client Credentials.
  8. Click the Roles tab and assign the SCIM Integration role. 
    Important:
    • To grant this role to your OAuth client, you must have this role assigned to your profile.
    • Do not assign other roles to your OAuth client or other permissions to the SCIM Integration role. If you do assign other roles or permissions, Token Duration that you set in step 6 reverts to the default of 86,400 seconds.

  9. Click Save.

    Genesys Cloud creates a Client ID and a Client Secret. Use these identifiers in the configuration of your identity management system.

For information about Genesys Cloud SCIM (Identity Management), see About Genesys Cloud SCIM (Identity Management) and Genesys Cloud SCIM (Identity Management) overview (Developer Center).