Today, several security issues and concerns could exist with using a standard API key implementation. OneTrust is committed to providing more secure solutions and supports the OAuth 2.0 authorization framework for a more advanced approach to external application access.
Note
A maximum of 500 OAuth 2.0 client credentials can be created per account.
You can create and manage client credentials that utilize the OAuth 2.0 authorization framework using the Credentials screen in Global Settings. When creating client credentials, you must be mindful of the organization in which you are creating them given that client credentials are assigned to the organization in which they are created. This means that APIs called using the client credentials will only be able to return objects accessible by the organizational group in which the client credentials were created.
Client credentials that appear on the Credentials screen also depend on the organization in which you are currently logged in. For example, say your organizational hierarchy contains a root organization named Global and two child organizations named North America and Europe. If you are currently within the Global organization, you will be able to see all client credentials created within the Global, North America, and Europe organizations. However, if you navigate to the North America organization, you will only be able to see client credentials created in the North America organization and will not have visibility into client credentials created in the Europe organization or Global organization.
Note
When viewing client credentials within the root organization, there is currently no way to identify in which organization each client credential was created on the Credentials screen. However, you can navigate to other sub-organizations to locate specific client credentials to determine in which organization it was created. Alternatively, you can incorporate the organization name within the name of the client credential to help you identify those details in the future.
To create OAuth 2.0 client credentials
Click the gear icon 
in the upper right-hand corner to access Global Settings.
On the menu, select . The Credentials screen appears.
-
Click the Add button. The Client Credentials section of the Add Client Credential screen appears.
-
In the Name field, enter a name for the client credential.
Note
The name cannot be modified once the client credential is created.
Optional: In the Description field, enter a description for the client credential.
-
In the Access Token Lifetime field, select the amount of time that should pass before the access token expires. The following options are available:
1 Hour
1 Day
1 Week
1 Month
1 Year
Optional: Turn on the Restrict IP Addresses setting to restrict incoming communication to specific IP addresses. If this setting is enabled, enter an IP address in the Restrict IP Addresses field that appears. You can enter multiple IP addresses by clicking the Add icon button and entering an additional IP address in the field that appears.
-
Click the Next button. The Scope section appears.
Select one or multiple check boxes to indicate the scope that matches the level of access you want to grant to an application.
-
Click the Create button. The Client ID and Secret section appears.
-
In the Download Credential field, click the Download button. A .txt file containing the Client ID and Client Secret details will download to your local system.
Warning
The Client ID and Client Secret details should be saved to a secure location.
Click the Close button.
To edit a client credential
Click the gear icon 
in the upper right-hand corner to access Global Settings.
On the menu, select . The Credentials screen appears.
Click the link in the Name field for the client credential that you want to edit. The Client Credential Details screen appears.
-
Click the Edit button. Editable fields become available.
-
Modify the client credential details on the Details tab and the Scope tab, as needed.
Note
Changes made to the Access Token Lifetime and the Scope will only affect new access tokens and will not affect existing access tokens. Changes made to the Restricted IP Addresses will apply to both existing and new access tokens. In addition, the client credential name and Client ID cannot be modified.
Click the Save button.
To upload a mutual authentication certificate
Site Admins can upload a Mutual Transport Layer Security (mTLS) certificate for generated client credentials when using a custom branded URL.
Click the gear icon 
in the upper right-hand corner to access Global Settings.
On the menu, select . The Credentials screen appears.
Click the link in the Name field for the client credential for which you want to upload a Mutual Transport Layer Security (mTLS) certificate. The Client Credential Details screen appears.
Click the Edit button. Editable fields become available.
-
Turn on the Enable Mutual Authentication setting. The Mutual Authentication Certificate field appears.
Click the Upload button. The Upload Certificate modal appears.
Click the Select File button and upload a valid X.509 certificate.
Click the Save button. The details of the uploaded certificate appear.
Click the Save button.
Access tokens are used to authorize applications to access an API. Since API responses can contain user information, access tokens must be kept confidential and secure.
Note
The following procedure details how to generate a token from within Global Settings in the OneTrust application. Alternatively, you can generate a token using the POST /v1/oauth/token API in the OneTrust Developer Portal.
Click the gear icon 
in the upper right-hand corner to access Global Settings.
On the menu, select . The Credentials screen appears.
Hover over the client credential for which you want to generate a token, and click the Context Menu icon 
that appears.
-
On the menu, select . The Access Token modal appears.
In the Client Secret field, enter the Client Secret details that you previously saved when the client credential was created.
Click the Generate button. The Access Token field appears with the access token.
Click the Copy button. The access token is copied to your computer's clipboard.
Click the Close button.
To reset the Client Secret details
Client Secrets can be revoked, if necessary. For example, if the Client Secret was unintentionally exposed, you can reset the current Client Secret and download a new Client Secret using the following steps.
Note
Resetting a Client Secret will not invalidate any access tokens. However, any existing integrations that use the old Client Secret will no longer work and will need to be updated.
Click the gear icon 
in the upper right-hand corner to access Global Settings.
On the menu, select . The Credentials screen appears.
Hover over the client credential that you want to reset secret for, and click the Context Menu icon that appears.
-
On the menu, select . The Reset Secret modal appears.
Note
The Reset Secret modal can also be accessed by clicking the Reset Secret button on the Client Credential Details screen.
-
Click the Reset button. The Client Reset Secret modal appears.
-
In the Download Credential field, click the Download button. A .txt file containing the Client ID and Client Secret details downloads to your local system.
Warning
The Client ID and Client Secret details should be saved to a secure location.
To delete a client credential
Client credentials can be deleted, if necessary. For example, if all previous access tokens need to be invalidated, you can delete the client credential using the following steps.
Note
Deleting client credentials will invalidate any access tokens. Any existing integrations using the old client credentials will no longer work and will need to be updated.
Click the gear icon 
in the upper right-hand corner to access Global Settings.
On the menu, select . The Credentials screen appears.
Hover over the client credential that you want to delete, and click the Context Menu icon that appears.
-
On the menu, select . The Delete Client Credential modal appears.
-
Click the Delete button.
Note
Client credentials can also be deleted by clicking the Delete button on the Client Credential Details screen.
To use OAuth 2.0 Client Credentials to make calls for external system integrations
Once you've created the client credential, you can generate the respective access token either through the OneTrust application or through the POST /v1/oauth/token API in the OneTrust Developer Portal. You can use this token to authorize external system integrations that may communicate with OneTrust APIs and integration webhooks. This is achieved by passing the access token in the header with the value as 'Bearer {OAuth Access Token}'.
