About AbiliTec Authentication
Learn about the AbiliTec API authentication process.
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 which 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. <<Is this paragraph necessary?>>
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: NEED UPDATED EXAMPLE
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 | 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 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. NEED NEW EXAMPLE
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
<<are these general and not specific to the AbiliTec API? there’s a note about the Data Services APIs?>
- The API Explorer drop down 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]. NEED EMAIL ADDRESS
- 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 NEED PORTAL UPDATE.
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.
<NEED: new example>
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 | Parameter Values |
|---|---|---|---|
| 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” |
OAuth Code Examples
LiveRamp APIs require OAuth 2.0 authentication. Use the available code samples to test your connection and make sure you're set up correctly before customizing them to meet your needs. Click the links below to download the samples.
- Java Code Samples NEED SAMPLES
- C# Code Samples NEED SAMPLES
- Python Code Samples NEED SAMPLES
Error Code References
<<NEED - explanation of what these error codes are - they say 'gateway error'>>
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 |
References
<<NEED - are these references for app developers or internal resources?>>
The official OAuth site can be found at http://www.oauth.net. It contains good history about the standard, but is somewhat out of date.
Google. "Using OAuth 2.0 for Login" (Mountain View, CA)
https://developers.google.com/accounts/docs/OAuth2Login
Internet Engineering Task Force. "The OAuth 2.0 Authorization Framework (RFC 6749)" (Fremont, CA: October 2012)
http://tools.ietf.org/html/rfc6749
OAuth.net. OAuth 2.0 Code libraries and code samples.
http://oauth.net/code/
Open ID Foundation. "OpenID Connect Basic Client Profile 1.0" (San Ramon, CA)
http://openid.net/specs/openid-connect-basic-1_0.html
Open ID Foundation. "OpenID Connect 1.0 Specification" (San Ramon, CA: February 26, 2014)
http://openid.net/connect/
Parecki, Aaron. "OAuth 2 Simplified." (Portland, OR: Aaron Perecki, 2014).
http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified
Updated over 3 years ago