Authentication
Twee mechanismen die makkelijk verward worden
Een API-sleutel zegt welk systeem aanroept. Een verifieerbaar credential zegt welke laag een derde mag lezen. Het tweede behandelen als een variant van het eerste is de duurste fout in een paspoortintegratie.
- Regeling
- Bearer
- Begrensd op
- Omgeving + functie
- Derden
- W3C-credentials
Definition
Hoe authenticeert u zich bij de paspoort-API?
Uw systemen tonen over HTTPS een in scope beperkte bearer-sleutel, uitgegeven per omgeving en per capability. Derden die beperkte paspoortniveaus lezen gebruiken helemaal geen sleutels: zij tonen een W3C Verifiable Credential, uitgegeven door een partij die het toegangsbeleid vertrouwt, en de resolver geeft het niveau terug waarop dat credential recht geeft.
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.
Verzoeken
Een sleutel tonen
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"]
# }Vergelijking
Sleutels en credentials naast elkaar
| 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 |
Praktijken
Wat wij aanbevelen
Eén sleutel per dienst
Zo heeft een lek een impactradius die u in één zin kunt beschrijven.
Scopes met minimale rechten
Een uitgiftepijplijn heeft nooit leestoegang tot afgeschermde lagen nodig.
Scheiding van omgevingen
Een sandboxsleutel kan by design geen productiepaspoorten bereiken.
Rotatie met overlap
Beide sleutels blijven geldig tijdens de wissel, zodat rotatie geen deploymentrace wordt.
Kortlevend waar mogelijk
Verloop op sleutels die door kortlevende workloads worden gebruikt, beperkt hoe lang een lek nog uitmaakt.
Controleer voordat u aanneemt
Het logboek laat zien wat een sleutel deed toen die geldig was — de basis om de blootstelling te beoordelen.
Antwoorden
Veelgestelde vragen
Wat is hier het verschil tussen een API-sleutel en een credential?
Een API-sleutel authenticeert uw systemen bij CirculeID en is begrensd tot wat uw organisatie mag. Een verifieerbaar credential authenticeert een derde — een recycler, reparateur of autoriteit — bij een paspoort en bepaalt welke laag die krijgt. Sleutels geven wij uit; credentials komen van wie het toegangsbeleid vertrouwt.
Hoe zouden sleutels moeten worden begrensd?
Nauw, en per dienst. Een uitgiftepijplijn heeft schrijftoegang tot paspoorten nodig en verder niets; een webshop heeft leestoegang tot de publieke laag nodig en verder niets. Scopen per functie betekent dat een gecompromitteerde sleutel in de ene dienst geen afgeschermde data van een andere blootlegt.
Zijn sandbox- en productiesleutels uitwisselbaar?
Nee, bewust niet. Sleutels dragen hun omgeving mee, zodat een sandboxsleutel geen productiepaspoorten kan raken en een productiesleutel niet per ongeluk in een testopstelling wordt gebruikt. Paspoorten zijn langlevende publieke artefacten; een per ongeluk uitgegeven productiepaspoort kunt u niet stilletjes verwijderen.
Hoe wordt sleutelrotatie afgehandeld?
Sleutels mogen overlappen: geef de nieuwe uit, rol hem uit, trek dan de oude in, met beide geldig in de tussentijd. Roteren zonder overlapvenster betekent een deploymentrace, en zo komt het dat organisaties uiteindelijk nooit roteren.
Wat gebeurt er als een sleutel uitlekt?
Trek hem meteen in; de intrekking werkt bij de volgende request en niet pas bij het verlopen van een cache. Het auditlogboek toont wat die sleutel deed toen hij geldig was, en dat is wat u nodig hebt om de blootstelling te beoordelen — en de reden dat nauw gescopete sleutels die beoordeling kort houden.
Next step
Een sandboxsleutel ophalen
Begrensd tot één functie, in een omgeving die niets echts kan raken.