Create an OAuth client

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 name is 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.
   Note: When HIPAA compliance is enabled for your organization, Genesys Cloud enforces an idle timeout of 15 minutes and this idle timeout is also applicable to tokens issued by OAuth clients. For more information, see HIPAA compliance.

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.