Authentication
Due meccanismi facili da confondere
Una chiave API dice quale sistema sta chiamando. Una credenziale verificabile dice quale livello un terzo ha diritto di leggere. Trattare la seconda come una variante della prima è l’errore più costoso di un’integrazione passaporto.
- Sistema
- Bearer
- Delimitato per
- Ambiente + funzionalità
- Terze parti
- Credenziali W3C
Definition
Come ci si autentica verso l’API del passaporto?
I vostri sistemi presentano su HTTPS una chiave bearer con ambito limitato, emessa per ambiente e per capacità. I terzi che leggono livelli riservati del passaporto non usano affatto chiavi: presentano una credenziale verificabile W3C emessa da una parte di cui la policy di accesso si fida, e il resolver restituisce il livello a cui quella credenziale dà diritto.
The separation matters because the two have different lifecycles. A key belongs to your integration and rotates on your schedule; a credential belongs to a recycler or an authority and is revoked when their permit lapses, not when your contract does.
Richieste
Presentare una chiave
curl https://api.circuleid.com/v1/passports/01/09506000134352 \
-H "Authorization: Bearer $CIRCULEID_API_KEY"
# Scope errors are explicit rather than a bare 403:
# {
# "error": "insufficient_scope",
# "required": "passports:read:restricted",
# "granted": ["passports:read:public", "events:write"]
# }Confronto
Chiavi e credenziali a confronto
| API key | Verifiable credential | |
|---|---|---|
| Authenticates | Your systems | A third party reading a passport |
| Issued by | CirculeID, to your organisation | A party the access policy trusts |
| Scoped by | Environment and capability | What the credential asserts |
| Revoked when | You rotate or a key leaks | A permit or accreditation lapses |
| Verified by | Us, on each request | Anyone, cryptographically |
| Lives in | Your secret manager | The holder’s own wallet or system |
Prassi
Che cosa consigliamo
Una chiave per servizio
Così una fuga ha un raggio d’impatto che puoi descrivere in una frase.
Ambiti a privilegio minimo
Una pipeline di emissione non ha mai bisogno dell’accesso in lettura ai livelli riservati.
Separazione degli ambienti
Per costruzione, una chiave sandbox non può raggiungere passaporti di produzione.
Rotazione con sovrapposizione
Entrambe le chiavi restano valide durante il cambio, così la rotazione non diventa una corsa al rilascio.
A vita breve dove possibile
Una scadenza sulle chiavi usate da carichi effimeri limita per quanto tempo una fuga conta.
Verifica prima di dare per scontato
Il registro mostra cosa ha fatto una chiave finché era valida: la base per valutare l’esposizione.
Risposte
Domande frequenti
Qual è qui la differenza tra una chiave API e una credenziale?
Una chiave API autentica i tuoi sistemi verso CirculeID ed è delimitata a ciò che la tua organizzazione può fare. Una credenziale verificabile autentica un terzo — riciclatore, riparatore, autorità — verso un passaporto e decide quale livello riceve. Le chiavi le emettiamo noi; le credenziali vengono da chi la policy di accesso riconosce.
Come vanno delimitate le chiavi?
In modo stretto e per servizio. Una pipeline di emissione ha bisogno dell’accesso in scrittura ai passaporti e di nient’altro; una vetrina ha bisogno dell’accesso in lettura al livello pubblico e di nient’altro. Delimitare per funzionalità significa che una chiave compromessa in un servizio non espone i dati riservati di un altro.
Le chiavi sandbox e produzione sono intercambiabili?
No, deliberatamente. Le chiavi portano con sé il proprio ambiente, così una chiave sandbox non può toccare passaporti di produzione e una chiave di produzione non può essere usata per errore in un banco di prova. I passaporti sono artefatti pubblici di lunga durata; un’emissione accidentale in produzione non si cancella in silenzio.
Come è gestita la rotazione delle chiavi?
Le chiavi possono sovrapporsi: emetti la nuova, distribuiscila, poi revoca la vecchia, con entrambe valide nel frattempo. Ruotare senza finestra di sovrapposizione significa una corsa al rilascio, ed è così che le organizzazioni finiscono per non ruotare mai.
Che cosa succede se una chiave viene esposta?
Revocala subito; la revoca ha effetto alla richiesta successiva e non alla scadenza di una cache. Il log di audit mostra che cosa ha fatto quella chiave finché era valida, ed è ciò che ti serve per valutare l’esposizione — nonché il motivo per cui delimitare bene le chiavi rende breve quella valutazione.
Next step
Ottieni una chiave sandbox
Limitata a una sola funzionalità, in un ambiente che non può toccare nulla di reale.