# 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](https://mediamathsupport.force.com/s/) 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](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2) 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](https://mediamathsupport.force.com/s/) 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


```bash
$ 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"
}
```


```json
{
  "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:


```bash
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 MediaMath Services

### Step 1. Register a MediaMath Client

Reach out to [MediaMath Support](https://mediamathsupport.force.com/s/) so we can work with you to create the `Client ID` and `Client Secret` for you to access the MediaMath API.

Try the OAuth Flow Yourself
We’ve provided sample files to help you quickly test the OAuth workflow:

- [📄 How to Use OAuth PoC (PDF)](/assets/how_to_use_oauth_poc.c05993b76162fd828216e0ac10239d22176634024be3ab9c1cab121d2a6aa9bf.9817d8cf.pdf)
- [🌐 MediaMath OAuth PoC (HTML)](/assets/mediamath_oauth_poc.54be26019f7437bbfc541c5b44d65bd8be2f7417c99ef571b8b0780915757585.9817d8cf.html)


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

To begin the OAuth process, direct the MediaMath 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:


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

Test Your Access Token
Once you have your access_token, try making a test API request using tools such as cURL, Postman, or the provided [📄 OAuth PoC HTML tool (PDF)](/assets/how_to_use_oauth_poc.c05993b76162fd828216e0ac10239d22176634024be3ab9c1cab121d2a6aa9bf.9817d8cf.pdf).
Make sure you include it in the Authorization header as:


```har
Authorization: Bearer ACCESS_TOKEN
```

If the token is valid, you should receive a successful API response.

#### (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`


```json
{
  "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`.


```bash
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.


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