Create an OAuth client

AI-generated summary

Genesys Cloud provides comprehensive OAuth client functionality for secure API authentication and third-party system integration, supporting four primary OAuth 2 authorization methods: Client Credentials, Code Authorization/PKCE, Token Implicit Grant (being deprecated), and SAML2 Bearer. OAuth client creation requires Admin access and specific permissions, with configurable token durations ranging from 300 to 172,800 seconds for standard implementations, extending up to 450 days for SCIM integration, and HIPAA compliance requiring 15-minute idle timeouts. The system supports up to 125 authorized redirect URIs and generates a one-time viewable client secret that can be regenerated. Client Credentials grant type enables single-step authentication exclusively for non-user applications like Windows Services or cron jobs, where applications exchange OAuth credentials for access tokens but cannot access user-specific APIs. Code Authorization/PKCE provides two-step authentication ideal for server-side API requests and thin desktop clients, offering maximum security, while Token Implicit Grant enables single-step browser-based authentication suitable for JavaScript and desktop applications with reduced security. SAML2 Bearer allows authentication using Security Assertion Markup Language assertions. For Client Credentials grant type, administrators must assign minimum required roles scoped to appropriate divisions, with role assignment requiring administrator permissions. OAuth client creation occurs through the Admin interface by configuring application credentials and authentication parameters, involving specification of an app name, optional description, and grant type selection. Upon creation, the system generates a Client Secret—a one-time viewable password proving application identity during token requests—which can be copied, viewed, or regenerated. The Client ID enables developers to configure the clientIds parameter in the framework.js file for Genesys Cloud Embeddable Framework implementations in both public and private deployments. For non-Client Credentials grant types, administrators must specify Authorized Redirect URIs where authorization codes are posted and exchanged for access tokens, with loopback IP redirect URIs able to omit port numbers. The platform maintains detailed audit trails tracking creation and modification details, provides granular scope-based permission management for most grant types, and offers comprehensive management tools for editing, deleting, and monitoring OAuth clients. SCIM integration enables identity management with extended token durations and requires the SCIM Integration role and OAuth > Client > Add permission. The Token Implicit Grant option is being deprecated in favor of PKCE grant type, requiring migration for compliance and stronger OAuth 2.0 security. Genesys Cloud OAuth clients integrate with identity management systems and support configuration with third-party providers including OneLogin, Microsoft Entra ID, and Okta.

Feature postponement: The Proof Key for Code Exchange (PKCE) grant type authorization in embedded clients has been temporarily postponed. Please check for updated availability information.

Feature deprecation: Genesys will deprecate the Token Implicit Grant (Browser) option for OAuth authorization. All existing customers are encouraged to migrate to Proof Key for Code Exchange (PKCE) grant type for OAuth 2 authorization. For more information about this deprecation, see .

PrerequisitesClick to expand

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.

Platform APIClick to expand

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 and is used when the app must authorize a request to an API endpoint. To see a list of Genesys Cloud Platform APIs, see the in the Genesys Cloud Developer Center.

Click Admin.
Under Integrations, click OAuth.
Click Menu > IT and Integrations > OAuth.
In the OAuth page, click Add client. The Add New Client page appears.
In the App Name field, enter the name of the application.
(Optional) In the Description field, enter the description.
In the Grant Types field, select a type for the grant. Grant Types set the way that 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: A single-step authentication process exclusively for use by non-user applications (for example 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 cannot access user-specific APIs (for example, GET /v2/users/me). If assigning roles for Genesys Cloud for Salesforce, see also OAuth client permissions for Genesys Cloud for Salesforce.
- Code Authorization / PKCE:
- A two-step authentication process where a user authenticates with Genesys Cloud and the client application is then 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 option is the most secure and ideal for websites where:
  - API requests are made on the server-side (for example, ASP.NET or PHP).
  - A thin client in some desktop applications authorizes the user and passes the auth code to a back-end server to exchange it for an auth token and make API requests.
- Token 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 (for example, JavaScript) and most desktop applications (for example, .NET WPF/WinForms or Java desktop programs).
- SAML2 Bearer: An authentication process wherein a client application can use a Security Assertion Markup Language (SAML2) assertion to request a bearer token. For more information, see Genesys Cloud single sign-on and identity provider solution.
  Note: A single Code Authorization or Implicit grant type can be used in all regions.
Click Next.
(Client Credentials grant type only) You must select the roles that must apply. No other grant types are affected by access control. This action opens a list of roles to choose from. In the Assign Roles table, in the Assigned column, enable the toggle available for each role. 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 that you want to associate 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 that use those grants can access the appropriate data. If a client credential grant is supplied by a third-party, check with the third party to understand the use of the grant and update the divisions for the roles appropriately.
Click Next.
For Client Credential grant type, enter the following information:
- Token Duration in seconds: Enter the required duration for the token. 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 two 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.
- For other grant types, enter the following details:
  - Token Duration in seconds: Enter the required duration for the token. 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 two 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.
  - Authorized redirect URIs (one per line, up to 125): The authorization code is posted to these URIs and are exchanged for an access token to use later to authenticate subsequent API calls.
    Note: For loopback IP redirect URIs, adding the allowed redirect URI without a port number (For example, http://localhost/) allows the application to listen on any free port for the Genesys Cloud response.
  - Scope: All grant types except Client Credentials have a Scope setting. Click the Scope box and view a list of scopes available to your app. As a best practice, select only the minimum scopes your app needs. For more information about scopes, see OAuth Scopes in the Developer Center.
Click Next.
Click Save. A message confirms that the client has been created.
In the Add New Client page, the Client Secret section appears. The Client Secret field displays a secret string that the application uses to prove its identity when the user requests for a token. This secret can also be referred as the application password.
Note: You can view this secret only once at the time of setup.
You can perform the following actions in this field:
- To view details about the password, click Show .
- To copy the password, click Copy .
- To generate a new secret code, click Generate new secret. The Generate New Client Secret? dialog box appears.
  - Click Confirm.
  - A message confirms that the password has been changed.
Click Finish. The Copy and Store Client Secret dialog box appears.
Click Confirm. The app you just created appears with the following section at the bottom of the page.
- Created By: Displays the name of the user who created the client.
- Date: Displays the creation date of the new client.
- Modified By: Displays the name of the user who modified the client details.
- Date: Displays the modification date of the client.

Your Genesys Cloud OAuth client is now ready to use.

Genesys Cloud Embeddable FrameworkClick to expand

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

You want to implement a public deployment.
You want to implement a private deployment that accesses the getAuthToken method in your framework.js file. For more information, see User.getAuthToken in the Genesys Cloud 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 Genesys Cloud Developer Center.

Click Admin.
Under Integrations, click OAuth.
Click Menu > IT and Integrations > OAuth.
Click Add client. The Add New Client page appears.
In the App Name field, enter the name of the application.
(Optional) In the Description field, enter the description.
In the Grant Types field, select the following option:
- Token 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 (for example, JavaScript) and most desktop applications (for example, .NET WPF/WinForms or Java desktop programs).
Click Next.
In the Token Duration in seconds field, enter the required duration for the token. 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.
Note: Genesys recommends that you set the token duration to 18 hours (64,800 seconds). This duration generally causes the token to expire outside an agent’s normal workday.
In the Authorized redirect URIs (one per line) box, add https://apps.mypurecloud.com/crm/index.html, customized according to your Genesys Cloud region.
Notes:
- Use the AWS region according to your deployment.
- 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.
In the Scope field, select the required scopes. You can also add more scopes. For a list of required scopes, see Administrator requirements for the Genesys Cloud embedded clients. For more information about scopes, see OAuth Scopes in the Developer Center.
Click Save. In the Add New Client page, the Client Secret section appears. The Client Secret field displays a secret string that the application uses to prove its identity when the user requests for a token. This secret can also be referred as the application password.
Note: You can view this secret only once at the time of setup.
You can perform the following actions in this field:
- To view details about the password, click Show .
- To copy the password, click Copy .
- To generate a new secret code, click Generate new secret. The Generate New Client Secret? dialog box appears
  - The Generate New Client Secret? dialog box appears. Click Confirm.
  - A message confirms that the password has been changed.
Click Finish.
The Copy and Store Client Secret dialog box appears. To confirm that you copied and stored the password, select the checkbox. If you proceed, you cannot view this password again.
Click Confirm. The app you just created appears with the following section at the bottom of the page.
- Created By: Displays the name of the user who created the client.
- Date: Displays the creation date of the new client.
- Modified By: Displays the name of the user who modified the client details.
- Date: Displays the modification date of the client.

Provide the Client ID to the developers, who in turn 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.

Genesys Cloud SCIMClick to expand

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.

Click Admin.
Under Integrations, click OAuth.
Click Menu > IT and Integrations > OAuth.
Click Add Client. The Add New Client page appears.
In the App Name field, enter the name of the application.
(Optional) In the Description field, enter the description.
In the Grant Types field, select Client Credentials. For more information about each grant, see the Platform API tab step 8.
Click Next.
In the Assign Roles table, in the Assigned column, assign the SCIM Integration role.
Note: 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 not assign other roles or permissions, the value you set in the Token Duration in seconds field reverts to the default value of 86,400 seconds. Also, include all divisions that you will manage with SCIM.
Click Next.
In the Token Duration in seconds field, enter the required duration for the token. The 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 same permissions.
Click Save. A message confirms that the client has been created. In the Add New Client page, the Client Secret section appears. The Client Secret field displays a secret string that the application uses to prove its identity when the user requests for a token. This secret can also be referred as the application password.
Note: You can view this secret only once at the time of setup.
You can perform the following actions in this field:
- To view details about the password, click Show .
- To copy the password, click Copy .
- To generate a new secret code, click Generate new secret. The Generate New Client Secret? dialog box appears
  - The Generate New Client Secret? dialog box appears. Click Confirm.
  - A message confirms that the password has been changed.
Click Finish.
The Copy and Store Client Secret dialog box appears. To confirm that you copied and stored the password, select the checkbox. If you proceed, you cannot view this password again.
Click Confirm. The app you just created appears with the following section at the bottom of the page.
- Created By: Displays the name of the user who created the client.
- Date: Displays the creation date of the new client.
- Modified By: Displays the name of the user who modified the client details.
- Date: Displays the modification date of the client.

You can further perform the following actions on this page:

Edit the client details by clicking the Edit Client button.
Delete the client created by clicking the Delete Client button.

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

[NEXT] Was this article helpful?

Get user feedback about articles.

Create an OAuth client View summary

[NEXT] Was this article helpful?

Create an OAuth client