API Authorization


OAuth is an open protocol to allow secure API authorization in a simple and standardized way from desktop and web applications. Acxiom implements the OAuth 2.0 Authorization Framework.

The purpose of this section is to provide developer’s detailed instructions for implementing the OAuth and OpenID functionality built into Acxiom's Identity Association Service. All of the Acxiom APIs Acxiom publishes require OAuth 2.0 authentication.

We have included References on OAuth 2.0 for those who wish to delve deeply into the subject.

Which Grant Type Should I Use?

We strongly suggest you use the client credentials grant type unless you have a compelling reason not to. Please note that if you choose the password grant type you will be required to log onto the system and change your password every 45 days.

Client Credential Grant Type

The Client Credentials grant type lets the caller obtain an access token by just passing in the client id and client secret values. There is no user/resource owner being authenticated in this token. Client credential authorization is for situations where the client application needs to access resources or call functions in the resource server which are not related to a specific resource owner (e.g. user). For instance, obtaining a list of venues from Foursquare does not necessarily have anything to do with a specific Foursquare user.

The caller invokes the token endpoint and the access token is returned.

Figure 1
Flows in Client Credential Grant Type
OAuth Client Credential Grant Type in the Data Services API Platform

Because of the nature of the validation to get a token from this grant type, tighter controls are in place for its use. There are additional manual configuration steps needed before a user can use this particular grant type. See the Notes section at the end for more information on that. Also, see the code samples for this grant type to gain further understanding

Step 1: The Partner Application Makes a Token Request to Acxiom

When a partner application wants access to an Acxiom protected resource, it makes a call to the Acxiom authorization endpoint at https://login.myacxiom.com in order to obtain an OAuth client credential grant.

Shown below is an example of the request:

POST /api/v1/auth/oauth2/token


For this request specify the following parameters:

ParameterRequiredDescriptionParameter Values
client_idYesObtained at the time of partner application registration. 
client_secretYesObtained at the time of partner application registration. 
grant_typeYesMust be “client_credentials” 
Step 2: Acxiom Returns Access Token to Partner Application

If the access token request is valid and authorized, the token server issues the access token. Per the OAuth 2.0 specification, a refresh token is not allowed for the client credentials grant type.

{ "access_token":"920d8f37-5e10-453a-8e87-8e28ae37cc90","token_type":"Bearer","expires_in":3600 } 


The parameters in the response include:

ParameterRequiredDescriptionParameter Values
access_tokenYesThis is the access token that can be used for subsequent Acxiom service endpoint calls. 
token_typeYesMust be “Bearer”. 
expires_inYesExpiration time of the access token in seconds. 

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. HTTP response code 400 is returned. The token error response specification is here.


HTTP/1.1 400 BadRequestContent-Type:application/json { "error":"invalid_request","error_description":"Missing grant_type" }
ParameterRequiredDescriptionParameter Values
errorYes invalid_request
Step 3: Application Requests Access to Protected Resource

Once the application has the OAuth2 access token, it calls the appropriate API endpoint for the service it desires, passing the access token in the authorization header. Below is an example of how the token is used to call a protected resource. This needs to be done in TLS (i.e., https).

GET /v1/people/er/jsmith1test@acxiom.com
Authorization:Bearer 920d8f37-5e10-453a-8e87-8e28ae37cc90
authorization headerYesThis is “Bearer”, space, “access token value” (from the response of the token endpoint)
  • 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 DSAPI_Team@acxiom.com.
  • 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.

OAuth Code Examples

The purpose of this section is to provide developers code samples, along with instructions for implementing those code samples. All of the APIs that Acxiom publishes require OAuth 2.0 authentication. These code samples will let you test your connection and make sure you're set up properly before customizing them to meet your needs. We have samples of code available for Java, C# and Python programming languages for the OAuth 2.0 client credential and password grant types. Click the links below to download the samples.

• Java Code Samples
• C# Code Samples
• Python Code Samples

Error Code References

Gateway error codes are prefaced with '000-'.

Error Code
000-1000Bad Request
000-1001Invalid Host
000-1002Invalid Target
000-1003Invalid Gateway
000-1010Invalid URI
000-1020Invalid/missing version
000-1004Invalid Gateway Error
000-1005Invalid Content-type
000-2000Rate Limit Exceeded
000-2001Rate Limit Exceeded
000-2100Malformed request syntax
000-2101Malformed request syntax
000-2102Malformed request syntax
000-2110Malformed request syntax
000-2111Malformed request syntax
000-2112Malformed request syntax
000-2120Malformed request syntax
000-2121Malformed request syntax
000-2122Malformed request syntax
000-3000Route failure
000-3010Multi-route failure
000-4000Forbidden: Invalid path
000-1205token parse error
000-1208Invalid Gateway Error
000-5000Service Unavailable
000-5001Bad Request
000-5003Not Found
000-5004Not Found


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)

Internet Engineering Task Force. "The OAuth 2.0 Authorization Framework (RFC 6749)" (Fremont, CA: October 2012)

OAuth.net. OAuth 2.0 Code libraries and code samples.

Open ID Foundation. "OpenID Connect Basic Client Profile 1.0" (San Ramon, CA)

Open ID Foundation. "OpenID Connect 1.0 Specification" (San Ramon, CA: February 26, 2014)

Parecki, Aaron. "OAuth 2 Simplified." (Portland, OR: Aaron Perecki, 2014).