Autenticazione REST API per Italia
API key bearer, OAuth2 PKCE e mTLS — autenticazione REST API per i clienti in Italia.
Architettura — API key (server-to-server)
Genera API key in dashboard, con scope di paese (Italia) e ruolo (sola lettura, ordini, fatture, admin). Invia come Authorization: Bearer cm_live_… su TLS 1.3. Prefissi per ambiente (cm_live_, cm_test_), rotazione zero-downtime con finestra di overlap di 24h. Non includere mai le key in codice client-side — per quei flussi usa OAuth2. IVA 22% e gli altri default Italia sono dedotti dallo scope ma sovrascrivibili per richiesta tramite campo country.
Come integrarlo — OAuth2 con PKCE (delegato)
Per app end-user (mobile, SPA, portali partner) usa OAuth2 authorisation code con PKCE (S256). Autorizza su https://auth.corpmerch.com/oauth2/authorize, scambia il code per un access token (1 ora) e refresh token (30 giorni, ruotato all'uso). Scope a privilegio minimo: orders.read, orders.write, invoices.read ecc. I refresh token sono device-bound; il theft detection invalida la famiglia in caso di riuso.
Operatività e casi limite — mTLS (tenant ad alta sicurezza)
I clienti enterprise possono richiedere mTLS in aggiunta al bearer. Carica il certificato client (PEM, RSA 2048 o ECDSA P-256) da dashboard o via Trust API. Terminiamo il mTLS all'edge di Milano, validiamo catena e SAN contro la tua config tenant, poi accettiamo. Rotazione cert con coppia primary/secondary. L'auth verso Sistema di Interscambio (SdI) avviene lato nostro con le nostre credenziali — il tuo mTLS riguarda solo l'API Corp-Merch.
Domande frequenti
Key o OAuth — quando?
Server-to-server nel tuo datacenter o VPC: API key. Delegato end-user (mobile, partner portal): OAuth2 PKCE. Setup misti usano entrambi.
Come si ruota una key?
Crea una nuova key in parallelo, deploya, poi revoca la vecchia dopo 24h di overlap. La dashboard mostra last-used timestamps.
mTLS è standard o a pagamento?
Incluso in Enterprise; add-on su Pro. Cert self-signed accettati con manual pinning; CA pubbliche preferite.
Scadenza token?
Access token 1 ora; refresh token 30 giorni, ruotati all'uso, con theft detection.
E l'autenticazione verso SdI?
SdI è canale downstream — ci autentichiamo per tuo conto con le nostre credenziali. Il routing IVA 22% è trasparente.