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
invalid_client
invalid_grant
unauthorized_client
invalid_scope

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.