About Retrieval API Authentication
Learn about the Retrieval API authentication process.
Step 1: Request an Account ID and a Secret key from LiveRamp.
You need your service account credentials to obtain an access token. Contact your LiveRamp representative for your client-id and client-secret.
Make sure to protect your credentials. You will be responsible for any traffic that uses your credentials.
Once you have the client-id and client-secret, you can post the access token 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 a Retrieval 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 30 days ago