Autenticazione
Bearer token
Invia Authorization: Bearer sk_live_… a ogni richiesta. Non mettere mai una chiave in un URL o in un cookie; non esiste un altro header per essa. Una chiave mancante, malformata, revocata o scaduta risponde 401 unauthorized, senza dire quale.
Una chiave appartiene a uno spazio di lavoro. GET /v1/workspaces/current lo restituisce insieme al suo piano. Se invii X-Workspace-Id, deve indicare lo spazio di lavoro della chiave.
Creare le chiavi
Crea le chiavi nell’app in Settings → API. Editor, amministratori e il proprietario creano chiavi che agiscono come loro stessi; gli amministratori possono anche rinominare e revocare quelle di chiunque. I visualizzatori non possono creare chiavi. Uno spazio di lavoro può contenere 50 chiavi attive.
Il segreto viene mostrato una sola volta e ne conserviamo solo l’hash. L’API non consente chiamate dal browser tra origini diverse: tieni le chiavi sul tuo server.
Ambiti
Scegli gli ambiti quando crei la chiave; non si possono cambiare in seguito (ruota o crea una nuova chiave). Una richiesta richiede l’ambito della route, indicato accanto a ogni route nel riferimento API. Una chiave che non lo ha riceve 403 forbidden con details.reason missing_scope.
codes:readElenca e leggi i codici, le loro versioni e attività; scarica i file; avvia e leggi esportazioni ed esecuzioni in blocco.Viewer o superiorecodes:writeCrea, modifica, metti in pausa, sposta ed elimina codici; crea in blocco; carica loghi e file.Editor o superioreanalytics:readStatistiche dello spazio di lavoro e dei singoli codici, e record di ogni scansione.Viewer o superioresubmissions:readRisposte ai moduli ospitati. Contengono dati personali di chi risponde.Editor o superiorefolders:readElenca e leggi le cartelle.Viewer o superiorefolders:writeCrea, rinomina, sposta ed elimina cartelle. La condivisione resta nell’app.Editor o superioretemplates:readElenca e leggi i modelli di design.Viewer o superioretemplates:writeCrea, modifica ed elimina i modelli di design.Editor o superioredomains:readElenca i domini personalizzati e il loro stato, per sceglierne uno per i nuovi codici.Viewer o superiorewebhooks:readElenca gli endpoint webhook e le loro consegne.Admin o superiorewebhooks:writeRegistra, modifica ed elimina endpoint webhook; invia un evento di prova; reinvia. Solo per gli admin.Admin o superioretags:readElenca i tag dello spazio di lavoro e quanti codici hanno ciascuno.Viewer o superioretags:writeCrea, rinomina, cambia colore ed elimina tag. Per assegnare i tag ai codici serve Codes · write.Editor o superiorecards:readElenca e leggi i biglietti da visita del team e le loro statistiche.Viewer o superiorecards:writeCrea, modifica, disattiva e riassegna i biglietti da visita. Solo per gli admin.Admin o superioreconversions:writeInvia conversioni dal tuo server (ordini, iscrizioni) per il funnel delle scansioni.Editor o superioreRuoli
Una chiave non fa mai più di quanto consente il ruolo attuale del suo creatore, al massimo come Editor. Se il creatore viene retrocesso a visualizzatore, la chiave perde subito gli ambiti di scrittura; quando il creatore lascia lo spazio di lavoro, le sue chiavi vengono revocate.
webhooks:read e webhooks:write sono l’eccezione: solo gli amministratori e il proprietario possono concederli, e continuano a funzionare solo finché il creatore è ancora amministratore.
Restrizioni di cartella e IP
Una chiave può essere limitata a un massimo di 20 cartelle e alle loro sottocartelle, per esempio una chiave per cartella cliente. Allora non vede nulla al di fuori, e una scrittura altrove risponde 403 con details.reason api_key_folder_restricted.
Una chiave può anche essere limitata a un massimo di 20 intervalli IP in forma CIDR (203.0.113.0/24). Una chiamata da qualsiasi altro posto risponde 403 con details.reason ip_not_allowed.
Scadenza e rotazione
Una chiave può scadere in una data che scegli. Ruotare una chiave emette un nuovo segreto con lo stesso nome, gli stessi ambiti e le stesse restrizioni; il vecchio segreto continua a funzionare per 24 ore per impostazione predefinita (da 0 a 168), così puoi distribuire il nuovo senza interruzioni. La revoca ha effetto immediato.
Cosa non può fare una chiave
Le chiavi chiamano solo le route del riferimento API. Il tuo account, membri e inviti, fatturazione, impostazioni dello spazio di lavoro, condivisione, configurazione dei domini e le chiavi API stesse restano nell’app: quelle route rispondono a una chiave con 403 forbidden e details.reason session_required.