LiveRamp implements 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 AbiliTec API.

Client Credentials

The Client Credentials are used to obtain an access token by passing the client id and client secret values.

Client credential authorization is used in situations where a client application needs to access resources or call functions in the resource server that are not related to a specific resource owner (for example, a user). For instance, obtaining a list of venues from Foursquare does not necessarily have anything to do with a specific Foursquare user.

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. See the code samples for this grant type to gain further understanding.

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 /api/v1/auth/oauth2/token
HTTP/1.1Host:https://login.myacxiom.com
Content-Type:application/x-www-form-urlencoded

client_id=3d2f9b04-7d98-4959-85a3-a2bffb92f041&client_secret=b6e2807e-62b9-4a63-b831-e0d22dc49f95&grant_type=client_credentials

Required token request parameters

Parameter	Required	Description
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
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 AbiliTec API endpoint, passing the access token in the authorization header. Transport Layer Security (TLS) is required to call an AbiliTec API endpoint.

The example below shows how to use a token to make a call to an AbiliTec API endpoint.

GET /v1/people/er/[email protected]
HTTP/1.1
Host:api.acxiom.com.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)

Notes

The API Explorer dropdown for this grant type says "Client Credentials.”
For the Data Services APIs, before tokens generated from this grant type can be used to call Data Services APIs, the client id (also referred to as API key), along with the tenant id, and role, has to be registered with the Data Services product team. To begin this registration, email [email protected].
The registration of a client id in the demo/sandbox environment is separate from the registration of that same client id in the production environment. In order to acquire access for the demo/sandbox, please register on the portal.

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.

POST /api/v1/auth/oauth2/token HTTP/1.1
Host: login.myacxiom.com client_id=891de212¬d3cb¬4482¬8c70¬76b647d7eb32&client_secret=217dc803¬0fa1¬48b4¬a362¬492f1dea

Parameter	Required	Description
refresh_token	Yes	The refresh_token code returned by LiveRamp.
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 “refresh_token”

Error Code References

Gateway error codes are prefaced with '000-'.

Error Code ${gatewayErrorCode}	Message ${gatewayResponseMessage}
000-1000	Bad Request
000-1001	Invalid Host
000-1002	Invalid Target
000-1003	Invalid Gateway
000-1010	Invalid URI
000-1020	Invalid/missing version
000-1xxx
000-1004	Invalid Gateway Error
000-1005	Invalid Content-type
000-1100	Forbidden
000-1101	Forbidden
000-2000	Rate Limit Exceeded
000-2001	Rate Limit Exceeded
000-20xx
000-2100	Malformed request syntax
000-2101	Malformed request syntax
000-2102	Malformed request syntax
000-2110	Malformed request syntax
000-2111	Malformed request syntax
000-2112	Malformed request syntax
000-2120	Malformed request syntax
000-2121	Malformed request syntax
000-2122	Malformed request syntax
000-21xx
000-3000	Route failure
000-3010	Multi-route failure
000-4000	Forbidden: Invalid path
000-1200
000-1201	Unauthorized
000-1202	Unauthorized
000-1205	token parse error
000-1208	Invalid Gateway Error
000-5000	Service Unavailable
000-5001	Bad Request
000-5002	Unauthorized
000-5003	Not Found
000-5004	Not Found