Chiavi e autenticazione

Chiave pubblicabile e chiave segreta

La chiave pubblicabile viaggia nell'URL come ?key=. È pubblica per scelta: sta nel sorgente della tua pagina e funziona solo dalle origini elencate per essa. La chiave segreta viaggia come Authorization: Bearer <key> ed è solo per il tuo server. Un browser non può nemmeno inviarla al servizio: Authorization non è nella lista consentita del CORS.

Origini consentite

Ogni chiave pubblicabile porta un elenco di al massimo 20 origini: schema, host e porta esattamente come li invia il browser, ad esempio https://shop.example.com. Una richiesta da qualsiasi altra origine viene rifiutata con 403 origin_not_allowed, preflight compreso, e il servizio non risponde mai con Access-Control-Allow-Origin: *. L'elenco è un segnale, non un'autenticazione: le vere difese sono il prezzo calcolato lato server e i limiti di frequenza.

Chiavi di test

Uno shop reale può creare fino a 3 chiavi di test (pk_test_…, sk_test_…). Una chiave di test calcola i prezzi sulla tua bozza convalidata più recente, così puoi provare una modifica prima di pubblicarla. Non viene fatturata, i suoi ordini non inviano né webhook né e-mail e scade dopo 30 giorni. Test e reale non si mescolano mai: un preventivo di test si verifica solo con una chiave segreta di test, un ordine di test è visibile solo a una chiave di test e una chiave reale non ne vede mai uno. Una chiave di test può elencare http://localhost come origine.

Il token di progetto

I progetti salvati sono legati a un cliente, non a un login. Il primo POST /cfg/v1/projects emette un token casuale (cfgpt_…) e lo restituisce una sola volta; l'embed lo conserva e lo invia come X-Cfg-Project-Token a ogni successiva chiamata di progetto. Il token di un altro cliente, la chiave di un altro shop e un id sconosciuto ricevono tutti la stessa risposta 404.

Rotazione senza interruzioni

La rotazione si fa nella console, e ogni tipo ha una sovrapposizione, così nulla si rompe durante il passaggio.

• Chiave pubblicabile: la nuova chiave mantiene lo stesso elenco di origini; la vecchia continua a funzionare per 168 ore per impostazione predefinita (al massimo 720).
• Chiave segreta: mostrata una sola volta; la vecchia chiave continua ad autenticare per 24 ore per impostazione predefinita (al massimo 720).
• Chiave di firma dei preventivi: la nuova chiave firma da ora in poi; i preventivi firmati dalla vecchia chiave si verificano ancora e possono ancora essere ordinati per un massimo di 31 giorni.
• Segreto del webhook: durante un passaggio entrambi i segreti firmano ogni consegna per 7 giorni, come due valori v1=, così il tuo ricevitore può gestire l'uno o l'altro.

Cosa non va mai in un browser

La chiave segreta e il segreto del webhook (whsec_…). Tienili nell'ambiente del tuo server, mai in una pagina, in un repository o in un log. Se uno dei due trapela, ruotalo nella console.