# Front Amazon SP-API

## When to use this

Amazon Selling Partner API enforces a shared concurrency limit per
application. Teams often hit credential sprawl with Login with Amazon (LWA):
one credential per caller, or one developer app per caller. Pin a regional
SP-API host, store one refresh token as a managed credential, and hand each
caller a short-lived pool key.

Authorization-code click-to-connect and Restricted Data Tokens are out of
scope. Use a refresh token you already have from an existing Amazon app.

## Origins to pin

Pick the regional host your app already calls:

| Host | Region |
|---|---|
| `https://sellingpartnerapi-na.amazon.com` | North America |
| `https://sellingpartnerapi-eu.amazon.com` | Europe |
| `https://sellingpartnerapi-fe.amazon.com` | Far East |

One pool, one region. Put multiple hosts on one pool only when those hosts
must share the same concurrency budget.

## Setup

1. Create a pool and pin the SP-API origin under **Settings**.
2. On **Credentials**, add an **OAuth 2.0 refresh token** credential: LWA
   client id, client secret, and refresh token. Set the token URL to
   `https://api.amazon.com/auth/o2/token` and the access-token header to
   `x-amz-access-token`.
3. On the pool **Settings**, choose **Managed** custody and **OAuth 2.0
   refresh token**, then attach that credential.
4. Set **Max concurrency** to your safe Amazon limit (or use **Adaptive**
   with that value as the max).
5. Mint a pool key under **Access**.
6. Point callers at `https://‹pool›.swarmvia.cloud/...` instead of the Amazon
   host. Send `X-Swarmvia-Key`.

```bash
curl -sS "https://sp-na.swarmvia.cloud/orders/v0/orders?MarketplaceIds=ATVPDKIKX0DER" \
  -H "X-Swarmvia-Key: $POOL_KEY" \
  -H "Accept: application/json"
```

The pool exchanges the refresh token, caches the access token, and sends
`x-amz-access-token`. When the pinned origin is a
`sellingpartnerapi-*.amazon.com` host it also sends `x-amz-date` and, if
the caller omitted `User-Agent`, `swarmvia`. Callers never see the LWA
secret or refresh token.

## Tips

- One Amazon developer app can serve many pool keys. Rotate the credential
  when you rotate the LWA secret; keys stay the same.
- Enable **Retry on 429** so transient Amazon throttles are absorbed at the
  edge.
- SigV4/IAM is not required for SP-API seller calls.

## See also

- [Credentials](/docs/credentials)
- [Pool settings](/docs/pools/settings)
- [Concurrency](/docs/pools/concurrency)