The Retrieval API utilizes the OAuth 2.0 Authorization framework. OAuth provides secure API authorization in a simple and standardized way from desktop and web applications. The information in this section describes the OAuth and OpenID functionality built into the Retrieval API.
Client credentials are used to obtain an access token by passing the client id and client secret values.
Authentication workflow
Because of the need for a secure token validation process, tight controls are in place. There are additional manual configuration steps in place before a user can use client credentials to obtain a token. See the Notes section at the end for more information. Also, see the code samples for this grant type to gain further understanding <<Is this paragraph/information for internal development?>>
Step 1: The partner application makes a token request to LiveRamp
When a partner application wants access to a LiveRamp protected resource, it makes a call to the LiveRamp authorization endpoint: /vi/oauth2/token to obtain an OAuth client credential grant.
Shown below is an example of the request:
POST /token
HTTP/1.1 Host: https://us.identity.api.liveramp.com
Content-Type: application/x-www-form-urlencoded
client_id=companyname=client&client_secret=b6e2807e-62b9-4a63-b831-e0d22dc49f95&grant_type=client_credentials
Required token request parameters
Parameter | Required | Description | Parameter Values |
|---|---|---|---|
client_id | Yes | Obtained at the time of partner application registration. | |
client_secret | Yes | Obtained at the time of partner application registration. | |
grant_type | Yes | Must be “client_credentials” |
Step 2: LiveRamp returns an access token to the partner application
If the access token request is valid and authorized, the token server issues the access token.
{ "access_token":"920d8f37-5e10-453a-8e87-8e28ae37cc90","token_type":"Bearer","expires_in":3600 }
Response parameters
Parameter | Required | Description | Parameter Values |
|---|---|---|---|
access_token | Yes | This is the access token that can be used for subsequent LiveRamp service endpoint calls. | |
token_type | Yes | Must be “Bearer”. | |
expires_in | Yes | Expiration time of the access token in seconds. |
Invalid or unauthorized token requests
If the token request is invalid or unauthorized, the token error response is returned as an application/JSON in the entity body of the HTTP response. And HTTP response code 400 is returned.
HTTP/1.1 400 BadRequestContent-Type:application/json { "error":"invalid_request","error_description":"Missing grant_type" }
Error parameter
Parameter | Required | Description | Parameter Values |
|---|---|---|---|
error | Yes | invalid_request |
Step 3: Application requests access to protected resource
Once the application has the OAuth2 access token, it calls the Retrieval API endpoint, passing the access token in the authorization header. Transport Layer Security (TLS) is required to call a Retrieval API endpoint.
The example below shows how to use a token to make a call to an AbiliTec API endpoint.
POST /v1/people/[email protected]
HTTP/1.1
Host:us.identity.api.liveramp.com
Authorization:Bearer 920d8f37-5e10-453a-8e87-8e28ae37cc90
Accept:application/json
Authorization parameter
Parameter | Required | Description |
|---|---|---|
authorization header | Yes | This is “Bearer”, space, “access token value” (from the response of the token endpoint) |
Token Expiration
Following the OAuth 2.0 specification, a refresh token is not allowed for the client credentials. A new token request must be made to obtain a new access token. TLS is required.
Error Code References
When more specific error information can be returned by the application, an error document will be returned which contains an application-level error code. See "Error Document" for more information.
Cloudflare error codes
All client requests are routed through Cloudflare for additional security. This means you might receive an error code from Cloudflare itself in some scenarios, such as when calls are made from an IP address that is not whitelisted. These error codes are described here: https://support.cloudflare.com/hc/en-us/sections/200820298-Cloudflare-Errors.
Updated 3 months ago