OAuth Authentication

The Audience Manager REST API follows OAuth 2.0 standards for token authentication and renewal.

Contents:

Password Authentication Workflow

Password authentication secure access our REST API. The following table outlines the workflow for password authentication from a JSON client in your browser.

Tip: Encrypt access and refresh tokens if you store them in a database.
Process Step Description
Request API Access
Contact your Partner Solutions manager. They will provide you with an API client ID and secret. The ID and secret authenticate you to the API.
Note: If you'd like to receive a refresh token, specify that when you request API access.
Request the Token
Pass in a token request with your preferred JSON client. When you build the request:
  • Use a POST method to call https://api.demdex.com/oauth/token.
  • Convert your client ID and secret to a base-64 encoded string. Separate the ID and secret with a colon during the conversion process. For example, the credentials testId:testSecret convert to dGVzdElkOnRlc3RTZWNyZXQ=.
  • Pass in the HTTP headers Authorization:Basic <base-64 clientID:clientSecret> and Content-Type: application/x-www-form-urlencoded. For example, your header could look like this:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Set up the request body as follows:
    grant_type=password&username=<your AudienceManager user name>&
    password=<your AudienceManager password>
Receive the Token
The JSON response contains your access token. The response should look like this:
{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

The "expires_in" key represents the number of seconds until the access token expires. As best practice, use short expiration times to limit exposure if the token is ever exposed.

Refresh Token

Refresh tokens renew API access after the original token expires. If requested, the response JSON in the password workflow includes a refresh token. If you don't receive a refresh token, create a new one through the password authentication process.

You can also use a refresh token to generate a new token before the existing access token expires.

If your access token has expired, you receive a 401 Status Code and the following header in the response:

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

The following table outlines the workflow for using a refresh token to create a new access token from a JSON client in your browser.

Process Step Description
Request the New Token
Pass in a refresh token request with your preferred JSON client. When you build the request:
  • Use a POST method to call https://api.demdex.com/oauth/token.
  • Convert your client ID and secret to a base-64 encoded string. Separate the ID and secret with a colon during the conversion process. For example, the credentials testId:testSecret convert to dGVzdElkOnRlc3RTZWNyZXQ=.
  • Pass in the HTTP headers Authorization:Basic <base-64 clientID:clientSecret> and Content-Type: application/x-www-form-urlencoded. For example, your header could look like this:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • In the request body, specify the grant_type:refresh_token and pass in the refresh token you received in your previous access request. The request should look like this:
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e
Receive the New Token
The JSON response contains your new access token. The response should look like this:
{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

Authorization Code and Implicit Authentication

The Audience Manager REST API supports authorization code and implicit authentication. To use these access methods, your users need to log in to https://api.demdex.com/oauth/authorize to get access and refresh tokens.