OAuth 2.0 Authentication

Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view this page in the new Integration APIs space of our documentation.

OAuth 2.0 is only available on the /ads endpoint

When integrating order reporting via API, you will need to integrate the /orders endpoint with Basic authentication and your secret API key.

Client ID and Client Secret

The client_id and the client_secret will be provided by your Technical Account Manager. The Client Secret is private and should not be shared.

Requesting Access Tokens

To obtain an Access Token, you must send a request containing the client_id and client_secret. To do that, the Retailer must make a POST request to the Epsilon Retail Media Authorization Server endpoint:

https://$BASE_URL/v1/oauth2/token

/oauth2/token only provides the relevant token. You will use these tokens to interact with the various integration endpoints.

Your request will require a Basic Authorization sent via the Authorization request header containing the Retailer’s client_id and client_secret base64 encoded:

Authorization: "Basic" + base64encode(client_id + ":" + client_secret)

You will need to add the following parameter using the application/x-www-form-urlencoded format in the HTTP request body:

grant_type=client_credentials

The request will look like the following:

POST https://$BASE_URL/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded id+key>
grant_type=client_credentials

Receiving your Access Token

The response will contain the following information

• access_token: The access token to be used when calling the Epsilon Retail Media APIs

• expires_in: The amount, in seconds, until the access token expires

• token_type: The type of the token returned. It will be always Bearer in this case

A sample response is below

{
  "access_token": "xxxxx.yyyyy.zzzzz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Using the Token

Making calls against the Epsilon Retail Media API endpoints can be done by simply adding the Access Token generate to the Authorization header on the request Authorization: “Bearer “ <access_token>

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Bearer <access_token>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["category:Cupboard/Snacks"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

Request Errors

Invalid Client

If the client_id or client_secret sent in the request is incorrect, then you will receive a response like this:

{
  "error": "invalid_client"
}

Make sure you are using the correct credentials. Double-check your client_id and client_secret and make sure you're using the Basic Authorization correctly when calling the /token endpoint. ##Invalid Request An invalid request error will be returned from the Authorization Server if the request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.

{
  "error": "invalid_request"
}

Ensure to:

• Only include grant_type=client_credentials to the request body

• Set the correct Content-Type to the request header