> For the complete documentation index, see [llms.txt](https://docs.jentis.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jentis.com/data-activation/connectors/amazon-ads/amazon-ads-events-api-capi-v2.md).

# Amazon Ads Events API (CAPI v2)

The Amazon Ads Events API (CAPI v2) requires a valid OAuth **access token** on every request. Amazon's access tokens are short-lived (1h TTL). \
Therefore the connector generates and refreshes it automatically in the background. To do that, it needs  credential from you, which you provide once via constants. Detailed below.

## Setting up Authentication

There are **two supported ways** to provide the necessary credentials for access\_token generation. You only need to use one of them.

#### Option 1: Provide a Refresh Token directly

<https://advertising.amazon.com/API/docs/en-us/guides/get-started/retrieve-access-token>

If you (or your development team) already have an Amazon Ads OAuth refresh token — for example because you've previously completed the Login with Amazon (LWA) authorization flow yourself — you can enter it directly to its constant

**Constants required:**

| Constant                           | What to enter                                            |
| ---------------------------------- | -------------------------------------------------------- |
| `Amazon Ads OAuth - Client Id`     | The Client ID of your Login with Amazon security profile |
| `Amazon Ads OAuth - Client Secret` | The Client Secret of that same security profile          |
| `Amazon Ads OAuth - Refresh Token` | Your existing refresh token, e.g. `Atzr\|xxxxxxxx...`    |

The connector uses these three values to request a fresh access token whenever it needs one, and caches it until it's close to expiring.

**Note:** Amazon refresh tokens are generally valid for about a year from the moment they're issued, or until revoked. If yours is revoked in Amazon's console, the connector cannot recover on its own; you'll need to switch to Option 2 to reauthorize or create a new refresh\_token and replace it in JENTIS.

#### Option 2: Provide a one-time Authorization Code

<https://advertising.amazon.com/API/docs/en-us/guides/get-started/create-authorization-grant>

If you don't already have a refresh token, you can instead authorize once through Amazon's consent screen and hand the connector the resulting **authorization code**. The connector exchanges it for a refresh token and access token automatically, and only needs to do this once. After it behaves exactly like Option 1 using the refresh token it generated for itself.

**Constants required:**

| Constant                                | What to enter                                             |
| --------------------------------------- | --------------------------------------------------------- |
| `Amazon Ads OAuth - Client Id`          | The Client ID of your Login with Amazon security profile  |
| `Amazon Ads OAuth - Client Secret`      | The Client Secret of that same security profile           |
| `Amazon Ads OAuth - Authorization code` | The one-time code Amazon returns after you approve access |
| `Amazon Ads OAuth - Redirect URL`       | The exact redirect URI used when the code was issued      |

**How to get the authorization code:**

1. An authorized user (on Amazon Ads / Advertiser account) must do these steps:
   1. Navigate to the following URL with replacing the {{CLIENT\_ID}} and {{REDIRECT\_URL}} with your values\
      <https://www.amazon.com/ap/oa?scope=advertising::campaign_management&response_type=code&client_id={{CLIENT_ID}}&state=State&redirect_uri={{REDIRECT_URL}}>
2. After they approve access, Amazon redirects back to that URI with a `code` query parameter attached.
3. Copy that `code` value into the `Amazon Ads OAuth - Authorization code` constant, and make sure `Amazon Ads OAuth - Redirect URL` is set to **exactly** the redirect URI used in step 1 (same scheme, same trailing slash, no differences at all).
4. Start a preview with an Amazon Ads Events API tag set to active, so the authentication steps can be done by JENTIS.

**Important — the code is single-use and short-lived:**

* It expires roughly 5 minutes after being issued.
* It can only be redeemed once, if it's already been submitted anywhere (including a failed attempt), it's dead and a new one must be generated.
* Once the connector successfully exchanges it, it stores the resulting refresh token internally.
  * In this case you don't need to fill out the Authorization code field again unless you're deliberately reauthorizing (e.g. after revoking access).
* To reauthorize (for example, if access was revoked), repeat steps 1–4 above with a brand-new code. Leaving the old, already-used code in place will not trigger a new exchange.

***

### Quick comparison <a href="#quick-comparison" id="quick-comparison"></a>

|                               | Option 1: Refresh Token                                                                    | Option 2: Authorization Code                                      |
| ----------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| Setup effort                  | You perform the OAuth exchange yourself beforehand                                         | The connector performs the one-time exchange for you              |
| What you provide              | A long-lived refresh token                                                                 | A short-lived, single-use code + matching redirect URI            |
| Best for                      | Teams that already have a refresh token, or prefer managing the OAuth handshake themselves | Teams who just want to click through Amazon's consent screen once |
| Recovery if access is revoked | Enter a new refresh token                                                                  | Generate and enter a new authorization code                       |

***

### Other required constants (not related to authentication) <a href="#other-required-constants-not-related-to-authentication" id="other-required-constants-not-related-to-authentication"></a>

These are required regardless of which option above you use:

| Constant                       | What to enter                                                                                                                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Amazon Advertiser Account ID` | Your DSP Advertiser ID (not the DSP Entity ID — that's not supported)                                                                                                                    |
| `Amazon API endpoint`          | The regional API host for your account: `advertising-api.amazon.com` (NA), `advertising-api-eu.amazon.com` (EU), or `advertising-api-fe.amazon.com` (FE) — without the `https://` prefix |


---

# 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://docs.jentis.com/data-activation/connectors/amazon-ads/amazon-ads-events-api-capi-v2.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.