# Autenticazione per credential version (2.x Cognito vs 3.x LwA)

> **Knowledge base interna** — non è traduzione della doc Amazon. Consolida il
> contratto di autenticazione così come è **implementato nella libreria** e
> **verificato contro** la doc ufficiale e i client interni del gruppo.
> Aggiornare questa pagina nella stessa PR che cambia i fatti descritti.
>
> Indice della doc: [../../README.md](../../README.md) · Riferimento cURL ufficiale (tradotto): [../get-started/using-curl.md](../get-started/using-curl.md)

## In una riga

Con la Creators API **è la credential version, non la region, a decidere il flusso di token**: le `2.x` usano **Cognito**, le `3.x` usano **Login with Amazon (LwA)**. Il piano dati (`https://creatorsapi.amazon`) e le operazioni sono identici per tutte le versioni: cambia solo *come si ottiene il bearer token* e *come si scrive l'header `Authorization`*.

Quindi, alla domanda ricorrente «per le credenziali v3.2 servono altre API?»: **no, nessuna API dati aggiuntiva**. Serve un **endpoint di auth diverso** (LwA `api.amazon.co.uk/auth/o2/token`), che è già gestito dalla libreria. Gli stessi `client_id`/`client_secret` della credenziale Creators fungono da credenziali LwA: non c'è una registrazione separata da fare.

## Tabella endpoint token (fonte: doc ufficiale)

| Region | Version | Flusso | Token endpoint |
| :-- | :-- | :-- | :-- |
| NA (Nord America) | 2.1 | Cognito | `https://creatorsapi.auth.us-east-1.amazoncognito.com/oauth2/token` |
| EU (Europa) | 2.2 | Cognito | `https://creatorsapi.auth.eu-south-2.amazoncognito.com/oauth2/token` |
| FE (Estremo Oriente) | 2.3 | Cognito | `https://creatorsapi.auth.us-west-2.amazoncognito.com/oauth2/token` |
| NA (Nord America) | 3.1 | Login with Amazon | `https://api.amazon.com/auth/o2/token` |
| EU (Europa) | 3.2 | Login with Amazon | `https://api.amazon.co.uk/auth/o2/token` |
| FE (Estremo Oriente) | 3.3 | Login with Amazon | `https://api.amazon.co.jp/auth/o2/token` |

> [!NOTE]
> La region della tabella determina **solo** quale endpoint token usare. Le credenziali funzionano globalmente su tutti i marketplace: per chiamare un marketplace diverso imposta l'header `x-marketplace` e il parametro `marketplace` sul locale desiderato (con un Partner Tag valido per quel marketplace e l'accesso Creators approvato in quella region).

## Contratto per flusso

### 2.x — Cognito

| | Valore |
| :-- | :-- |
| Content-Type del token | `application/x-www-form-urlencoded` |
| Body | `grant_type=client_credentials&client_id=…&client_secret=…&scope=creatorsapi/default` |
| Scope | `creatorsapi/default` (slash singolo) |
| `Authorization` sulle chiamate API | `Bearer <token>, Version <credentialVersion>` |

Le credenziali possono essere passate nel body oppure come `Authorization: Basic base64(client_id:client_secret)` (vedi [using-curl](../get-started/using-curl.md#token-generation-for-v2x-credentials)).

### 3.x — Login with Amazon (LwA)

| | Valore |
| :-- | :-- |
| Content-Type del token | `application/json` |
| Body | `{"grant_type":"client_credentials","client_id":"…","client_secret":"…","scope":"creatorsapi::default"}` |
| Scope | `creatorsapi::default` (**doppio due-punti**) |
| `Authorization` sulle chiamate API | `Bearer <token>` — **senza** il suffisso `, Version …` |

Le due differenze che fanno inciampare più spesso sono il **body JSON** (non form-urlencoded) e lo **scope con `::`**. Il terzo è che le 3.x **non** vogliono `, Version` nell'header: il token da solo identifica già la credenziale, e inviare il suffisso può far fallire la chiamata.

### Comune a entrambi

- **Base API**: `https://creatorsapi.amazon` (tutte le region).
- Header obbligatori sulle chiamate: `Authorization`, `Content-Type: application/json`, `x-marketplace: <dominio marketplace>` (es. `www.amazon.it`).
- **Token cache**: `expires_in` è 3600 s (1 ora). Va messo in cache e riusato, non ri-ottenuto a ogni richiesta.

## Caveat operativi (verificati sul campo, NON nella doc ufficiale)

> [!IMPORTANT]
> **Le credenziali v3 spesso non sono abilitate agli endpoint feed.**
> `POST /catalog/v1/listFeeds` e `/catalog/v1/getFeed` con una credenziale 3.x
> possono rispondere **`HTTP 404`** anche quando l'autenticazione è andata a buon
> fine: significa che quella credenziale/account non è abilitata ai feed. Per i
> **feed in Europa/Italia usa una credenziale 2.2**, oppure passa dagli endpoint
> **report**, oppure da una sorgente diretta del file.
> Fonte: `gclid-mapper` (`CreatorsApiClient::throwHelpfulFeedError`), che usa la 3.2 in produzione.

> [!WARNING]
> **Rate limit dell'endpoint token Cognito (2.x): 300 richieste / 5 minuti per client.**
> Ri-ottenere il token a ogni richiesta porta a `HTTP 429`. È un motivo in più per
> rispettare la cache del token. (Documentato anche nella doc ufficiale:
> [Token Endpoint Rate Limiting](../troubleshooting/error-codes-and-messages.md).)

## Dove è implementato

- **Questa libreria** (fonte di verità): [`src/CreatorsApiClient.php`](../../../src/CreatorsApiClient.php)
  - `TOKEN_ENDPOINTS`, `LWA_VERSIONS`, `getAccessToken()`, `authorizationHeader()`.
- **Consumer interni** che hanno la stessa auth reimplementata a mano e che dovranno migrare su questa libreria (vedi [CLAUDE.md](../../../CLAUDE.md) → *Stella polare*):
  - `data-layer` → `lib/CreatorsAPI/com/amazon/creators/auth/OAuth2Config.php` (`getTokenEndpoint()`, `isLwaCredentialVersion()`, `getScope()`).
  - `gclid-mapper` → `src/Report/Amazon/CreatorsApiClient.php` (`v2Token()`, `v3Token()`, `authorizationHeader()`). Usa la **3.2**.

Le quattro fonti (libreria, doc ufficiale `using-curl`, `data-layer`, `gclid-mapper`) sono state confrontate e **concordano al 100%** su endpoint, formato body, scope e header per tutte le versioni 2.x/3.x.

## Riferimenti ufficiali

- [Usare cURL — Regional Endpoints + generazione token v2.x/v3.x](../get-started/using-curl.md)
- [Header e parametri comuni di richiesta](../concepts/common-request-headers-and-parameters.md)
- [Migrare dalla PA-API](../migrating-to-creatorsapi-from-paapi.md)
- [Codici e messaggi di errore](../troubleshooting/error-codes-and-messages.md)
