Managing OAuth 2.0 API Keys

OAuth 2.0 Application Programming Interface (API) Keys are opaque tokens used to authenticate requests to access resources. OAuth 2.0 API Keys are long-lived access tokens that can be used to integrate with external third-party applications. In contrast to client credentials, where the Client ID and Secret are used to generate a bearer token, the OAuth 2.0 API Key is an opaque token itself, which means that it does not contain any information within the token. Therefore, it can be directly passed in the Authorization header with a bearer schema to access the resource.

For more information on including this API key in third-party applications, see To use OAuth 2.0 API Keys to make calls for external system integrations.

Note:

A maximum of 500 OAuth 2.0 API keys can be created per account.

Using API Keys

You can create and manage API keys that utilize the OAuth 2.0 authorization framework using the API Keys tab of the Client credentials screen in Global Settings. When creating API keys, you must be mindful of the organization in which you are creating them given that API keys are assigned to the organization in which they are created. This means that APIs called using the API keys will only be able to return objects accessible by the organizational group in which the API keys were created.

API keys that appear on the API Keys tab of the Client 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 API keys 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 API keys created in the North America organization and will not have visibility into API keys created in the Europe organization or Global organization.

Note:

When viewing API keys within the root organization, there is currently no way to identify in which organization each API key was created on the API Keys tab of the Client credentials screen. However, you can navigate to other sub-organizations to locate specific API keys to determine in which organization it was created. Alternatively, you can incorporate the organization name within the name of the API key to help you identify those details in the future.



Field
Description
Name

Name of the OAuth 2.0 API Key. Click the link in the Name field to access the API Key Details screen.

Creation date

Date and time that the OAuth 2.0 API Key was created.

Created by

Name of the user who created the OAuth 2.0 API Key.

Description

Description for the OAuth 2.0 API Key.

To create an OAuth 2.0 API Key

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Navigate to the API Keys tab.
  4. Click the Add button. The Enter new API key details section on the Create API Key screen appears.


  5. In the Name field, enter a name for the OAuth 2.0 API Key.
  6. Optional: In the Description field, enter a description for the OAuth 2.0 API Key.
  7. Optional: In the API key lifetime field, select the amount of time that should pass before the OAuth 2.0 API Key expires. The default API Key lifetime is 1 hour, but can be changed. The following options are available:

    • 1 Hour

    • 1 Day

    • 1 Week

    • 1 Month

    • 1 Year

  8. 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 and entering an additional IP address in the field that appears.
  9. Click the Next button. The Select API Scope section appears.


  10. Select one or multiple check boxes to indicate the scope that matches the level of access you want to grant to an application.
  11. Click the Create button. The API key created section appears.


  12. In the Download API key field, click the Download button. A .txt file containing the OAuth 2.0 API Key will download to your local system.
    Attention:

    The OAuth 2.0 API Key should be saved to a secure location.

  13. Click the Close button.

To edit an OAuth 2.0 API Key

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Navigate to the API Keys tab.
  4. Click the link in the Name field for the OAuth 2.0 API Key that you want to edit. The API key details screen appears.

  5. Click one of the fields. Editable fields become available.


  6. Modify the OAuth 2.0 API Key details on the Details tab and the Scope tab, as needed.
    Note:

    The OAuth 2.0 API Key name and lifetime cannot be modified after creation.

  7. Click the Save button.

To delete an OAuth 2.0 API Key

Note:

Once an OAuth 2.0 API Key is deleted, the OAuth 2.0 API Key can no longer be used for authorization.

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Navigate to the API Keys tab.
  4. Hover over the OAuth 2.0 API Key that you want to delete, and click the Context Menu icon that appears.
  5. On the Context menu, select Delete. The Delete API Key modal appears.


  6. Click the Delete button.
    Note:

    OAuth 2.0 API Keys can also be deleted by clicking the Delete button on the API key details screen.

To use OAuth 2.0 API Keys to make calls for external system integrations

Once you've generated the API key, you can use this information to make a call for external system integrations that may communicate with OneTrust OneTrust APIs and integration webhooks. This is achieved in two ways:

  1. Include the generated API key parameter in the Authorization Header for third-party application calls.


  2. Append the generated API Key as a Query String Parameter to the URL.
    CODE 
    https://staging.1trust.ninja/api/datasubject/v2/requestqueues/en-us?Authorization=Bearer+MDc5ZWI5Mzc4ZGMxNDViYzllMzRhYmFlNjZlNWFiMzE6WlVzN002ZGlBZWNtT1FJWDcwZFdzN0NaWUQxNVdQdXV=
    Tip:

These API keys are not for use in integrations to authenticate calls in OneTrust APIs. To make internal calls between OneTrust endpoints or webhooks between OneTrust products and data sources, please use the seeded actions available in the workflow builder. For more information, see Managing Custom Integrations.