Learn about the AbiliTec API authentication process.
The AbiliTec API uses the OAuth 2.0 Authorization framework. OAuth provides secure API authorization in a simple and standardized way from desktop and web applications. This section describes the OAuth and OpenID functionality built into the AbiliTec API.
Client credentials are used to obtain an access token by passing the client ID and client secret values.
This AbiliTec API reference includes the information that you need to use the AbiliTec API, including information about how to request an access token and how to resolve your PII data using the Match endpoint and the Lookup endpoint.
The AbiliTec API leverages the AbiliTec Identity Graph to allow you to resolve your data to individuals and households. API calls can be made using 1-to-1 real-time single transaction calls or batch request calls (using the batch request endpoint). The batch endpoint allows you to send up to 1000 records per call. For more information, see Single Transaction and Batch Request Calls.
The AbiliTec API Process
- Request an access token.
- Send your PII-based consumer data, such as name, address, phone number, or email address, to an AbiliTec API Match or Lookup endpoint.
- The API processes the request and then returns the applicable AbiliTec IDs along with any requested associated metadata:
- If a matching record is found in the AbiliTec Identity Graph, the API returns a maintained AbiliTec ID.
- If a matching record isn't found, the API returns a derived AbiliTec ID for each PII touchpoint (for calls to the Match endpoint only).
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. To gain further understanding, see the code samples for this grant type.
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 access token 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 | 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.
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 that contains an application-level error code. See "Error Documents" 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. See Cloudflare Errors for additional information.