> 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.