Authentication

MediaMath’s API allows third-party applications developed on the MediaMath API to obtain various levels of permission from a MediaMath Platform user to access the user’s data on the MediaMath Platform (exposed via the Execution & Management API) without storing the user’s username and password.

This section provides a detailed walk-through of the OAuth2 workflow on MediaMath Platform. Please reach out to your MediaMath account representative or MediaMath Support if you have any questions/feedback on the materials presented in this document.

If you're new to OAuth2, we highly recommend Digital Ocean's primer on the subject. Dynamically registered clients only support the Authorization Code Grant, as most MediaMath APIs require a user context.

MediaMath expects all application owners to protect API keys and secrets. Please be prepared to rotate API keys or secrets if they are compromised in any way.

Accessing the MediaMath APIs via OAuth2 As the Owner of a MediaMath Platform Account

Step 1. Register a MediaMath Application

Reach out to MediaMath Support and we will create the Client ID and Client Secret for you to access the MediaMath API.

Step 2. Use the Resource Owner / Password Grant to get an Access Token

$ http POST https://mediamath.auth0.com/oauth/token \
grant_type=password \
username=example@example.com \
password=somepassword \
audience="https://api.mediamath.com/" \
client_id="GFg6CdBuibi1tk9yOQk0wwlDU6vqwyoP" \
client_secret="CLIENT_SECRET"

{
    "access_token": "eyJ0eX...KACzrBhNEg",
    "expires_in": 86400,
    "token_type": "Bearer"
}

{
  "url": "https://mediamath.auth0.com/oauth/token",
  "method": "post",
  "body": "{\n  \"grant_type\": \"password\",\n  \"username\": \"USERNAME\",\n  \"password\": \"PASSWORD\",\n  \"audience\": \"https://api.mediamath.com/\",\n  \"scope\": \"\",\n  \"client_id\": \"YOUR_CLIENT_ID\",\n  \"client_secret\": \"YOUR_CLIENT_SECRET\"\n}",
  "headers": {
    "Content-Type": "application/json"
  }
}

Step 3. Call the API

Once the access_token has been obtained it can be used in subsequent API calls.

Make calls to the API by passing it as a Bearer Token in the Authorization header of the HTTP request:

http https://api.mediamath.com/api/v3.0/organizations \
Accept:application/json \
Authorization:"Bearer eyJ0e...BhNEg"

{
  "data": [
    {
      "id": 100000,
      "name": "Organization One",
      "entity_type": "organization"
    },
    {
      "id": 100001,
      "name": "Organization Two",
      "entity_type": "organization"
    },
    {
      "id": 100002,
      "name": "Organization Three",
      "entity_type": "organization"
    }
  ],
  "meta": {
    "count": 3,
    "total_count": 100,
    "offset": 0,
    "status": "success"
  }
}

Copy the Session ID

MediaMath is in the process of migrating all APIs to OAuth2, but some APIs are not fully migrated. To mitigate that, make a request to https://api.mediamath.com/api/v2.0/session with the Authorization:"Bearer ACCESS_TOKEN header, and copy the adama_session cookie header from the response. Use both the Authorization:"Bearer ACCESS_TOKEN" header and adama_session= cookie in all future requests.

Accessing the MediaMath APIs via OAuth2 As a Third Party Extending T1 Services

Step 1. Register a MediaMath Client

Reach out to developers@mediamath.com so we can work with you to create the Client ID and Client Secret for you to access the MediaMath API.

Step 2. Direct the user to authorize your client to access their account

To begin the OAuth process, direct the T1 user's browser to the /authorize endpoint. The user will enter their credentials on that page, and will be redirected to the redirect_uri with a code parameter in the query string. Store that code parameter and exchange it for an access_token in step 3.

Step 3. Exchange authorization code for an access_token

Now that you have an Authorization Code, you must exchange it for an Access Token that can be used to call your API. Using the Authorization Code (code) from the previous step, you will need to POST to the /oauth/token endpoint.

Step 4. Call the API

Once the access_token has been obtained it can be used to make calls to the API by passing it as a Bearer Token in the Authorization header of the HTTP request:

{
  "method": "GET",
  "url": "https://api.mediamath.com/api/v3.0/organizations",
  "headers": [
    { "name": "Content-Type", "value": "application/json" },
    { "name": "Authorization", "value": "Bearer ACCESS_TOKEN" }
  ]
}

(Important) Copy the Session ID

MediaMath is in the process of migrating all APIs to OAuth2, but some APIs are not fully migrated. To mitigate that, make a request to https://api.mediamath.com/api/v2.0/session with the Authorization:"Bearer ACCESS_TOKEN header, and copy the adama_session cookie header from the response. Use both the Authorization:"Bearer ACCESS_TOKEN header and adama_session= cookie in all future requests.

Getting a Refresh Token

You can only get a Refresh Token if you are implementing the Authorization Code Flow or Resource Owner Password Grant Flow.

To get a Refresh Token, you must include the offline_access scope when you initiate an authentication request through the authorize or token endpoint.

The response should contain both an access_token and a refresh_token

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "token_type": "Bearer"
}

Using a Refresh Token

To exchange the Refresh Token you received during authorization for a new Access Token, make a POST request to the /oauth/token endpoint in the Authentication API, using grant_type=refresh_token.

curl --request POST \
  --url 'https://YOUR_DOMAIN/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data refresh_token=YOUR_REFRESH_TOKEN

The response will include a new Access Token, its type, its lifetime (in seconds), and the granted scopes. If the scope of the initial token included openid, then a new ID Token will be in the response as well.

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}