--- title: Autenticazione description: Due metodi di autenticazione — chiave API (Bearer) e OAuth 2.0 con PKCE — più Idempotency-Key per nuovi tentativi sicuri e limiti per piano su v1. canonical: "https://www.tracepass.eu/it/docs/authentication" locale: it source: "https://www.tracepass.eu/it/docs/authentication" --- # Autenticazione > Due metodi di autenticazione — chiave API (Bearer) e OAuth 2.0 con PKCE — più Idempotency-Key per nuovi tentativi sicuri e limiti per piano su v1. TracePass v1 supporta due metodi di autenticazione. Una **chiave API** (un bearer token statico) è il più semplice — ideale per integrazioni server-to-server ed ERP. **OAuth 2.0 con PKCE** è per app di terze parti e assistenti AI che agiscono per conto di un utente con accesso scoped e revocabile. Entrambi arrivano come bearer token nell'header standard `Authorization`; ogni operazione di scrittura accetta anche un `Idempotency-Key`per nuovi tentativi sicuri. Disponibili su ogni piano incluso Free. I limiti giornalieri di chiamate si applicano solo a Free (100/giorno) e Basic (200/giorno); Starter e superiori sono illimitati. ## Chiavi API Generate le chiavi in **Developer → API keys** nella dashboard. Le chiavi sono associate allo spazio di lavoro: ogni chiave è legata a uno spazio di lavoro e ne eredita il piano, i limiti e la traccia di controllo. Le chiavi portano il prefisso `tp_` seguito da un suffisso casuale opaco — non esiste un prefisso live / test separato, né una sandbox con namespace per ambiente. Effettuate i test sul vostro spazio di lavoro Free o Basic se vi serve un ambiente non di produzione. Passate la chiave come bearer token su ogni richiesta: ```bash curl -sS https://app.tracepass.eu/api/v1/products \ -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" ``` **Tip —** Una chiave compromessa si revoca con un clic — aprite Developer → API keys, premete **Revoke**, e la chiave inizia a restituire 401 nel giro di pochi secondi. Le voci della traccia di controllo per la chiave rimangono, così potete riconciliare ciò che è stato scritto con essa. ## OAuth 2.0 (app autorizzate dall'utente) Quando costruite un'app che altri utenti TracePass collegano — o un assistente AI che un utente autorizza — usate OAuth 2.0 invece di chiedere loro di incollare una chiave API. L'utente approva scopes specifici su una schermata di consenso; il token di accesso che genera è limitato all'intersezione tra il suo ruolo nella dashboard e gli scopes concessi. Registrate la vostra app in **Developer → OAuth Apps** (o a livello programmatico tramite Dynamic Client Registration su `/api/oauth/register`). Supportiamo l'**authorization-code flow con PKCE** — i client pubblici (SPA / mobile / MCP) non hanno bisogno di un secret; i client server-side confidenziali ne ricevono uno. ### Il flusso I metadati di discovery si trovano su `/.well-known/oauth-authorization-server` (RFC 8414). In breve: (1) indirizzate l'utente a `/api/oauth/authorize` con il vostro `client_id`, `redirect_uri`, lo `scope` richiesto, `state` e un `code_challenge` PKCE (`S256`); (2) l'utente approva e noi reindirizziamo indietro con un `code` monouso; (3) scambiatelo su `/api/oauth/token` con il vostro `code_verifier` per un token di accesso di 15 minuti (più un refresh token se è stato concesso `offline_access`). I refresh token ruotano a ogni uso; revocate su `/api/oauth/revoke` (RFC 7009). ### Scopes Richiedete solo ciò di cui la vostra app ha bisogno — la schermata di consenso mostra all'utente esattamente questi. Uno scope di scrittura richiede inoltre che l'utente autorizzante abbia un ruolo nella dashboard con permessi di scrittura, quindi un viewer che concede `passports:write` comunque non può scrivere. Le chiavi API, al contrario, sono „tutto o niente“ e ignorano gli scopes. | Scope | Concede | | --------------- | ------------------------------------------------------- | | passports:read | Visualizzare prodotti e passaporti digitali di prodotto | | passports:write | Creare, aggiornare e pubblicare passaporti | | documents:read | Leggere documenti caricati ed estrazioni | | documents:write | Caricare documenti ed eseguire estrazioni AI | | suppliers:read | Visualizzare le richieste ai fornitori | | suppliers:write | Creare e gestire le richieste ai fornitori | | offline\_access | Emettere un refresh token (restare connessi) | **Tip —** Gli utenti vedono e disconnettono le app che hanno autorizzato in **Developer → OAuth Apps → Connected Apps**; la disconnessione revoca immediatamente i token dell'app. Potete eliminare le vostre app registrate dalla stessa schermata. ## Idempotency-Key Ogni `POST`, `PATCH` e `DELETE` sulla superficie v1 accetta un header `Idempotency-Key`. Inviate un UUID v4 (o qualsiasi stringa opaca ≤ 255 caratteri) per ogni operazione logica; la piattaforma memorizza la prima risposta per 24 ore e la riproduce se la stessa chiave + lo stesso spazio di lavoro si ripresentano. I nuovi tentativi di rete diventano sicuri — non creerete un passaporto in doppio perché il vostro client HTTP ha ritentato su un 5xx transitorio. ```bash curl -sS https://app.tracepass.eu/api/v1/passports \ -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \ -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \ -H "Content-Type: application/json" \ -d '{ "productId": "...", "gs1": { "gtin": "...", "serialNumber": "..." } }' ``` Riutilizzare la stessa chiave con un **corpo della richiesta diverso** restituisce`422 Unprocessable Entity` con `error: "Idempotency-Key has already been used with a different request body. Use a new key for the new request, or reuse the original body."` — la piattaforma non sovrascrive silenziosamente, perché si tratta quasi sempre di un bug del client. Generate una chiave nuova per operazioni effettivamente nuove. ## Limiti di frequenza Si applicano due soglie per giorno UTC, per spazio di lavoro: ### 1\. Budget di scrittura v1 — \`maxV1WritesPerDay\` Conta ogni `POST` / `PATCH` / `DELETE` sulla superficie v1\. Le letture non vengono conteggiate su questo contatore. ### 2\. Budget di lettura passaporti v1 — \`maxV1PassportsPerDay\` Conta ogni `GET` sugli endpoint dei passaporti (lettura singola + elenco paginato). Separato dal budget di scrittura, così un ERP che invia aggiornamenti non esaurisce la vostra quota di lettura e viceversa. | Piano | Scritture / giorno | Letture passaporti / giorno | | ---------- | ------------------ | --------------------------- | | Free | 100 | 100 | | Basic | 200 | 200 | | Starter | Illimitato | Illimitato | | Growth | Illimitato | Illimitato | | Scale | Illimitato | Illimitato | | Pro | Illimitato | Illimitato | | Enterprise | Illimitato | Illimitato | Quando raggiungete una delle due soglie la risposta è `429 Too Many Requests` con un corpo del tipo `{ "error": "API rate limit: 200 writes/day via /api/v1. Currently 200 today; requested 1. Retry tomorrow (UTC) or upgrade your plan." }`. La finestra si reimposta alle 00:00 UTC; non supportiamo finestre scorrevoli perché rendono il limite più difficile da interpretare a valle. Una quota separata — `maxDpps` — limita il totale dei DPP attivi nel vostro spazio di lavoro e viene applicata tramite una risposta `402` con un corpo `overage_required` quando il piano supporta l'eccedenza per passaporto. Si veda l'endpoint [Create a passport](/it/docs/create-passport) per il flusso di eccedenza. **Vi serve più margine?** Fate un upgrade del vostro piano nella dashboard (immediato) oppure contattate [support@tracepass.eu](mailto:support@tracepass.eu) per un preventivo Enterprise. Non applichiamo una tariffa per scansione sul visualizzatore pubblico del passaporto — contano solo le scritture tramite questa API. ## Cosa non supportiamo (ancora) Il grant OAuth **client-credentials** (identità macchina senza utente) e l'allow-listing degli IP sono nella roadmap ma non ancora rilasciati. Per il puro accesso server-to-server oggi usate una chiave API — generatene una per ogni integrazione così da poter revocare a livello di integrazione.