Create an OAuth client

AI-generated summary

Genesys Cloud OAuth clients enable applications to authenticate against the platform, make API requests, and sync entities with third-party systems through a structured configuration process. The platform supports four grant types designed for different use cases: Client Credentials for non-user applications requiring single-step authentication; Code Authorization/PKCE for server-side API requests offering two-step authentication and maximum security (recommended for new implementations); Token Implicit Grant for client-side browser and desktop applications with lower security (unavailable for new implementations after May 25, 2026); and SAML2 Bearer for single sign-on scenarios using Security Assertion Markup Language assertions. OAuth client creation requires the OAuth > Client – Add permission, with SCIM integration requiring additional SCIM Integration role assignment. The workflow involves accessing Menu > IT and Integrations > OAuth, entering an application name and optional description, and selecting an appropriate grant type. Client Credential grant configuration requires assigning minimum required roles already present in the administrator's profile, associating roles with divisions (defaulting to Home Division), specifying allowed IP addresses using CIDR ranges, and setting token duration between 300 and 172,800 seconds. All grant types require token duration configuration within this range, with HIPAA-compliant organizations enforcing an additional 15-minute idle timeout. Authorization Code and Implicit grants require configuration of authorized redirect URIs (up to 125) and scope selection limited to minimum required permissions. A single Code Authorization or Implicit grant type functions across all regions except FedRAMP, which requires dedicated Authorization Code grant configuration. Upon client creation, the system generates a Client Secret as a one-time viewable credential used for application authentication; this secret can be copied, viewed, or regenerated as needed. The configuration page displays metadata including creator name, creation date, modifier name, and modification date. For Genesys Cloud Embeddable Framework deployments, administrators generate a Client ID for use in the framework.js file, with token duration recommendations of 18 hours (64,800 seconds) to align with typical agent workday schedules. Additional redirect URIs may be required if dedicatedLoginWindow is enabled in framework.js. SCIM integration configuration follows the same OAuth client creation process but specifies Client Credentials as the grant type and assigns the SCIM Integration role to the OAuth client with all relevant divisions included. Token duration for SCIM integration can extend to 38,880,000 seconds (maximum 450 days) with a default of 86,400 seconds, with extended durations requiring appropriate role permissions. Genesys Cloud documentation provides comprehensive guidance on integrations, OAuth authentication mechanisms, Embeddable Framework deployment options, SCIM identity management configuration for multiple providers (OneLogin, Microsoft Entra ID, and Okta), and authorization versus authentication concepts, supplemented by a feedback mechanism enabling users to rate article helpfulness and submit structured feedback.

PrerequisitesClick to expand

OAuth > Client – Add permission
For Genesys Cloud SCIM:
- 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. Access API Explorer in the Developer Center.

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 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).
  Note: After 25 May, 2026 you can no longer create new OAuth clients using the Implicit Grant type. Existing OAuth clients configured with Implicit Grant will continue to function. Genesys recommends using Authorization Code Grant with PKCE for new implementations.
- 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 About single sign-on (SSO).
  Note: You can use a single Code Authorization or Implicit grant type across all regions except FedRAMP. The FedRAMP region requires a dedicated Authorization Code grant configuration.
Click Next.
For Client Credential grant type, perform the following steps:
1. Step 1: Assign Role:
  1. Select the roles that 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.
  2. Click Next.
2. Step 2: Allowed IP addresses:
  1. In the Allowed IP Addresses (one per line) field, add the CIDR range. Add one range per line.
  2. Click Next.
3. Step 3: Additional details:
  1. In the Token Duration in seconds field, 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.
  2. Click Next.
For other grant types, 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.
- 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 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:
- Code Authorization / PKCE (recommended): 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.
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 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 section steps 5-7.
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.

Loading...

Create an OAuth client

[NEXT] Was this article helpful?