Quick Start Guide: APIs

OneTrust APIs provide developers with an open framework to build and integrate external systems seamlessly into the OneTrust platform. This guide describes how to generate an access token, authorize requests, and start making API calls. Let’s get started!

Step 1: Generate Access Token

To get started with OneTrust APIs, you will first need to generate an access token. OAuth 2.0 Client Credentials and OAuth 2.0 API Keys can be created within Global Settings in the OneTrust application. When creating a Client Credential or API Key, you will need to select the necessary scope(s). OAuth scopes are required for each endpoint in order to send requests. Details about the OAuth scopes required for each endpoint are covered within the respective API Reference page for that endpoint. For more information, see OAuth 2.0 Scopes.

• OAuth 2.0 Client Credentials: If using OAuth 2.0 Client Credentials, you can generate the access token either within the OneTrust application (Global Settings > Access Management > Client Credentials > Client Credentials tab) or by calling the POST /v1/oauth/token API. The access token must then be passed in the header with the value as 'Bearer {OAuth Access Token}'. For detailed steps on creating OAuth 2.0 Client Credentials, see Managing OAuth 2.0 Client Credentials.
  • 🔑

    Generate OAuth Access Token

    Open Recipe
• OAuth 2.0 API Keys: If using OAuth 2.0 API Keys, the API Key acts as the access token, which can be generated within the OneTrust application (Global Settings > Access Management > Client Credentials > API Keys tab). The access token can then be passed either in the header or as a query parameter with the value as 'Bearer {OAuth Access Token}'. For detailed steps on creating OAuth 2.0 API Keys, see Managing OAuth 2.0 API Keys.

Step 2: Authorize Requests

Once you have your access token either as an OAuth 2.0 Client Credential or OAuth 2.0 API Key, you can proceed to authorizing your requests. All API endpoints are RESTful and support the standard HTTP verbs over HTTPS. With the exception of the SCIM endpoints, all the API endpoints are authorized via an API Key in the HTTP header. The SCIM endpoints are authorized via an OAuth 2.0 Access Token in the authorization header.

The following examples demonstrate authorizing requests:

Header (Client Credentials and API Keys)

GET /api/access/v1/external/organizations HTTP/1.1
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {oauth_access_token}

Query Parameter (API Keys only)

GET /api/access/v1/external/organizations?Authorization=Bearer+{oauth_access_token} HTTP/1.1
Host: https://trial.onetrust.com
Content-Type: application/json

Step 3: Make an API Call

Once you have added your access token to authorize your requests, you can start utilizing OneTrust APIs. Available OneTrust APIs are listed within the API Reference section and are organized by the various Clouds within the Trust Management Platform. Each OneTrust API in the Developer Portal has a reference page where you can review details on what the API does, applicable optional and required parameters, and sample responses.

1. Update Hostname

Each reference page lists the API URL at the top of the page. Most OneTrust APIs in the Developer Portal follow the API URL format https://{hostname}/{baseURL}/{endpoint}, where:

• {hostname} is the domain of the environment (i.e. trial.onetrust.com)
• {baseURL} is in the format api/{microservice}/{version}
  • {microservice} is the name of the OneTrust microservice to interact with (i.e. ConsentManager)
  • {version} is the version of the API endpoint (i.e. v2)
• {endpoint} is the unique API endpoint being queried

When the API URL contains customer.my.onetrust.com as the hostname, you would update this hostname with your respective OneTrust environment. For example, if your OneTrust environment is trial.onetrust.com, then the https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects API URL would become https://trial.onetrust.com/api/consentmanager/v2/datasubjects.

2. Input Parameter Values

You can then input values for all required parameters as well as any optional parameters available for the API. Please ensure that you are using the correct input/format indicated for each respective parameter that you are including in your request.

3. Send Request

After you have updated the hostname and filled out the necessary parameters, you can send the request. OneTrust web servers use HTTP Response Status Codes to communicate the result of processing requests. The most common response codes returned by OneTrust web servers are as follows:

2xx Success Codes indicate that the request was successfully processed. The following are the most common 2xx status codes returned by OneTrust web servers:

4xx Client Error Codes indicate that there was an error in either the request or the data. The following are the most common 4xx status codes returned by OneTrust web servers:

5xx Server Error Codes indicate that there was an internal error with the server. The following are the most common 5xx status codes returned by OneTrust web servers:

📘

Best Practices

OneTrust recommends coding against OneTrust's error or status codes rather than an HTTP response. OneTrust does not recommend coding against code descriptions or text strings since these may be subject to change.

Please review the reference pages in the API Reference section to find the required endpoints and view the related HTTP Response Status Codes.

Additional Resources

The following resources can be referenced when getting started with OneTrust APIs:

• For more information on OneTrust API rate limiting, see API Rate Limits.
• For the latest updates to OneTrust APIs, see the OneTrust Changelog.
• For downloading the API definition files (Swagger or OpenAPI Specification files), navigate to https://developer.onetrust.com/onetrust/openapi and access the required links.