Autenticazione

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-Keyper 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:

curl -sS https://app.tracepass.eu/api/v1/products \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

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.

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.

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 restituisce422 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.

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_requiredquando il piano supporta l'eccedenza per passaporto. Si veda l'endpoint Create a passport per il flusso di eccedenza.

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.