> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Amazon Ads App

> Connect Amazon Ads through your own Login with Amazon app (white-label) by pasting your client ID, client secret, and a refresh token.

Markifact supports two ways to connect Amazon Ads: using the built-in **Markifact app** (Quick Connect) or connecting through your own **Login with Amazon app** (Custom App). With a custom app, every request Markifact makes to the Amazon Advertising API runs under your app and your client ID, so your clients never see Markifact.

<Note>
  Custom app connections are available on the **Team** plan. See [White-label Connections](/core-concepts/white-label-connections) for the overview.
</Note>

***

## Quick Connect vs Custom App

| Feature                 | Quick Connect         | Custom App                                       |
| :---------------------- | :-------------------- | :----------------------------------------------- |
| **Setup Time**          | 1 minute              | 20-30 minutes, plus Amazon's API access approval |
| **App the client sees** | Markifact             | Yours                                            |
| **API rate limits**     | Markifact's client ID | Your client ID                                   |
| **White Label**         | No                    | Yes                                              |
| **Plan**                | All plans             | Team                                             |
| **Best For**            | Quick setup, testing  | Agencies, strict client requirements             |

***

## What You Need

Three values from your own Login with Amazon app:

| Value             | Where it comes from                                                                                                                          |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client ID**     | Your security profile in the [Amazon Developer console](https://developer.amazon.com/loginwithamazon/console/site/lwa/overview.html)         |
| **Client Secret** | The same security profile                                                                                                                    |
| **Refresh Token** | Minted against that app with the `advertising::campaign_management` scope, by the Amazon account that has access to the advertising accounts |

Amazon access tokens last one hour; Markifact refreshes them with your client ID and secret on every run. Refresh tokens stay valid until the user revokes the app.

<Note>
  Amazon rejects any Advertising API call whose `Amazon-Ads-ClientId` header does not match the app that issued the token, which is why Markifact stores the client ID alongside the refresh token and sends them together.
</Note>

<Note>
  **Already have your own authorization flow?** If your systems already hold a refresh token issued by your app with the scope below, skip to [Connect to Markifact](#connect-to-markifact).
</Note>

***

## Setting Up Your Custom Amazon Ads App

<Steps>
  <Step title="Create the Login with Amazon Security Profile">
    1. Open the [Login with Amazon console](https://developer.amazon.com/loginwithamazon/console/site/lwa/overview.html) and click **Create a New Security Profile**
    2. Enter the profile name, description, and a privacy policy URL. The profile name is the branding users see when they authorize
    3. Once created, open **Web Settings** and add a **Allowed Return URL** you control (for example `https://www.youragency.com/amazon-callback`). Amazon appends the auth code to this URL after authorization; the page does not need to do anything, but the URL must be HTTPS
    4. Copy the **Client ID** and **Client Secret**
  </Step>

  <Step title="Apply for Amazon Advertising API Access">
    The Advertising API is not open to every app. Apply through the [Amazon Advertising API onboarding](https://advertising.amazon.com/API/docs/en-us/guides/onboarding/overview) and wait for Amazon to allow-list your client ID. Agencies that already run their own integrations will have this in place; until it is approved, the profiles endpoint returns authorization errors.
  </Step>

  <Step title="Authorize and Get the Auth Code">
    1. Open the following URL in a browser, replacing the client ID and return URL. Use the regional login host that matches your advertiser: `amazon.com` for North America, `eu.account.amazon.com` for Europe, `apac.account.amazon.com` for the Far East

    ```bash theme={"dark"}
    https://www.amazon.com/ap/oa?client_id=YOUR_CLIENT_ID&scope=advertising::campaign_management&response_type=code&redirect_uri=https%3A%2F%2Fwww.youragency.com%2Famazon-callback&state=markifact
    ```

    2. Sign in as the Amazon account that has access to the advertising accounts you want to manage and click **Allow**
    3. Amazon redirects to your URL with `code=...` in the query string. Copy the value. Auth codes expire after a few minutes and can be exchanged once, so do the next step right away
  </Step>

  <Step title="Exchange the Auth Code for a Refresh Token">
    Run this request, replacing the values (the redirect URI must match the one used above exactly):

    ```bash theme={"dark"}
    curl -X POST "https://api.amazon.com/auth/o2/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=authorization_code" \
      -d "code=THE_AUTH_CODE" \
      -d "client_id=YOUR_CLIENT_ID" \
      -d "client_secret=YOUR_CLIENT_SECRET" \
      -d "redirect_uri=https://www.youragency.com/amazon-callback"
    ```

    The response contains `refresh_token`. Copy it.

    > **Important:** Keep this token secure. Anyone holding it, together with your client ID and secret, can act on every advertising account the user can reach.
  </Step>

  <Step title="Connect to Markifact">
    1. In Markifact, go to the [Connections](https://app.markifact.com/connections) page
    2. Click **Connect** on **Amazon Ads**
    3. Select the **Custom App (White-label)** tab
    4. Enter a **Connection Name** (for example "Acme Agency Amazon Ads")
    5. Paste your **Client ID**, **Client Secret**, and **Refresh Token**
    6. Click **Verify & Connect**

    Markifact refreshes the token once with your app, then reads the advertising profiles from the North America, Europe and Far East endpoints. Nothing is saved unless at least one region returns a profile.
  </Step>
</Steps>

***

## Selecting Your Connection

Custom app connections appear under the name you chose, with a **Custom app** badge on the Connections page. Select them in Amazon Ads nodes, agents, and MCP exactly like any other Amazon Ads connection, then pick the advertising profile in the node.

***

## Rotating or Replacing the Token

Add the connection again with the **same connection name** and the new values. Markifact replaces the stored credentials in place, so workflows and agents bound to the connection keep working.

***

## Troubleshooting

<Accordion title="Amazon rejected the client ID or client secret (invalid_client)">
  Check both values on your security profile in the Login with Amazon console. The client ID starts with `amzn1.application-oa2-client.`.
</Accordion>

<Accordion title="Amazon rejected the refresh token (invalid_grant)">
  The token was issued by a different security profile than the one whose client ID you pasted, or the user revoked the app under their Amazon account's **Login with Amazon** settings. Authorize again and paste the new refresh token.
</Accordion>

<Accordion title="Amazon Ads API rejected the credentials (UNAUTHORIZED)">
  The client ID and the refresh token must come from the same app. Amazon checks the `Amazon-Ads-ClientId` header against the token's issuing client and rejects a mismatch, so pasting a client ID from one security profile with a token from another always fails here.
</Accordion>

<Accordion title="Amazon Ads API refused access (403)">
  Your client ID has not been allow-listed for the Advertising API yet, or the token is missing the `advertising::campaign_management` scope. Check the onboarding status with Amazon and authorize again with the scope.
</Accordion>

<Accordion title="This Amazon account has no advertising profiles in any region">
  The account that authorized has no access to an advertising account. Invite it under **Account settings** > **User management** in the Amazon Ads console, then authorize again.
</Accordion>

***

## Summary

| Item              | Where to Find                                     | What It Looks Like                       |
| ----------------- | ------------------------------------------------- | ---------------------------------------- |
| **Client ID**     | Login with Amazon console > your security profile | `amzn1.application-oa2-client.abc123...` |
| **Client Secret** | Same security profile                             | `amzn1.oa2-cs.v1.abc123...`              |
| **Refresh Token** | Response of the auth code exchange                | `Atzr\|IwEBI...`                         |
| **Scope**         | Authorization URL                                 | `advertising::campaign_management`       |

***

## Related

<CardGroup cols={2}>
  <Card title="White-label Connections" icon="tag" href="/core-concepts/white-label-connections">
    Overview of custom app connections across channels
  </Card>

  <Card title="Get Report" icon="chart-line" href="/nodes/amazon_ads/amazon_ads_get_report">
    Pull Amazon Ads performance data
  </Card>
</CardGroup>