> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/data-api/api-overview/oauth-20-authentication.md).

# OAuth 2.0 Authentication

{% hint style="info" %}
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.
{% endhint %}

## 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:

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

{% hint style="info" %}
`/oauth2/token` only provides the relevant token. You will use these tokens to interact with the various integration endpoints.
{% endhint %}

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:

```http
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

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

```http
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:

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

```json
{
  "error": "invalid_request"
}
```

Ensure to:

* Only include `grant_type=client_credentials` to the request body
* Set the correct `Content-Type` to the request header


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.citrusad.com/retail-media-interface/integration/data-api/api-overview/oauth-20-authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.