When looking to retrieve consent for a single data subject from a client-side web application or mobile app, the standard OneTrust APIs have previously required the use of a proxy or intermediary server to handle the GET call with authentication either by API key or client credentials. The following article details the alternative Preferences API method for retrieving client-side consent preferences using a public key.

Using the highly available Preferences API

The Preferences API provides a method for retrieving client-side consent preferences that uses an authorization token with public key model, which maintains security while eliminating the need for an intermediary server-server API call. The Preferences API is optimized for client-side applications, such as websites or mobile apps, to retrieve the current status of consent for a single data subject quickly and securely in order to make just-in-time decisions about application behavior as it relates to the consent of the individual. The Preferences API uses a design that reduces query response time in comparison with the main API calls as well as supports higher contention and bypasses the API limits that are in place in APIs that rely on querying the main OneTrust database.

Request

The Get Data Subject's Preferences API retrieves a list of preferences with the current consent status for a data subject.

 Response

📘

Updates made through the Update Data Subject's Preferences in a Preference Center API will not reflect in the response.

If the public key in the authorization token matches the key stored in the OneTrust platform, the API will return the consent preferences for the data subject as:

{
  "preferences":[
    {
      "id":"97705ddl-7c2d-4d94-9486-3fd313ce3776",
      "purposeLastUpdatedDate":"2021-01-06T09:00:48.247481Z",
      "lastInteractionDate":"2021-01-06T09:00:48.247481Z",
      "consentDate":"2021-01-06T09:00:48.247481Z",
      "status":"ACTIVE",
      "expiryDate":"2021-01-07T12:00:00Z",
      "purposeVersion": 1,
      "topics":[],
      "customPreferences":{}
    },
    {
      "id":"077318f3-0cc6-49al-853c-3d5540bd85cf",
      "purposeLastUpdatedDate":"2021-01-06T09:00:48.247481Z", 
      "lastInteractionDate":"2021-01-06T09:00:48.247481Z",
      "consentDate":"2021-01-06T09:00:48.247481Z”,
      "status":"ACTIVE",
      "expiryDate":"2021-01-07T12:00:00Z",
      "purposeVersion": 1,
      "topics":[], 
      "customPreferences":{}
    }
  ],
  "syncGroups":{},
  "dataElements":{
    "Device": "iPhone 11",
    "Browser": "Safari"
    }
}

Possible status values

👍

For more information, see Data Subject Purpose Statuses in Universal Consent & Preference Management Transaction Types and Purpose Statuses .

ETag and Last-Modified support

The API supports If-None-Match and If-Modified-Since headers. This means that you can pass either an ETag or last modified date, and the API will respond with 304 Not Modified if the preferences have not changed.

🗒

Things to Know

Constructing an authorization token

• The authorization token sent in the header can be any signed JWT where the signature can be verified using a public key that is uploaded within Global Settings in the OneTrust platform. In addition, the “sub” claim must also match the data subject identifier.

Token expiration

• For instances where the JWT includes an “exp” claim for the expiration date, the service will return an Unauthorized response if the date is in the past.

Storing the public key

• In order for OneTrust to validate your requests, you will need to enter the public key sent in your authorization token within the OneTrust platform. Navigate to Global Settings and select Consent > Public keys.

👍

For more information on configuring the public key in Global Settings, see Storing Public Keys for Data Subject Authentication.