Authentication
Zwei Mechanismen, die leicht verwechselt werden
Ein API-Schlüssel sagt, welches System aufruft. Ein verifizierbarer Nachweis sagt, welche Stufe ein Dritter lesen darf. Den zweiten als Variante des ersten zu behandeln, ist der teuerste Fehler einer Pass-Integration.
- System
- Bearer
- Begrenzt nach
- Umgebung + Fähigkeit
- Dritte
- W3C-Credentials
Definition
Wie authentifiziert man sich gegenüber der Pass-API?
Ihre Systeme präsentieren über HTTPS einen im Umfang begrenzten Bearer-Schlüssel, ausgestellt je Umgebung und je Fähigkeit. Dritte, die eingeschränkte Passstufen lesen, nutzen überhaupt keine Schlüssel: Sie legen ein W3C Verifiable Credential vor, ausgestellt von einer Partei, der die Zugriffsrichtlinie vertraut, und der Resolver gibt die Stufe zurück, zu der dieses Credential berechtigt.
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.
Anfragen
Einen Schlüssel vorlegen
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"]
# }Vergleich
Schlüssel und Nachweise nebeneinander
| 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 |
Praktiken
Was wir empfehlen
Ein Schlüssel je Dienst
So hat ein Leck einen Wirkungsradius, den Sie in einem Satz beschreiben können.
Geltungsbereiche nach geringsten Rechten
Eine Ausstellungspipeline braucht nie Lesezugriff auf geschützte Stufen.
Umgebungstrennung
Sandbox-Schlüssel können konstruktionsbedingt keine Produktivpässe erreichen.
Überlappende Rotation
Beide Schlüssel gelten während der Umstellung, sodass die Rotation kein Deployment-Wettlauf wird.
Kurzlebig, wo möglich
Ein Ablaufdatum auf Schlüsseln kurzlebiger Workloads begrenzt, wie lange ein Leck relevant bleibt.
Prüfen Sie, bevor Sie annehmen
Das Protokoll zeigt, was ein Schlüssel getan hat, solange er gültig war — die Grundlage für die Bewertung der Exposition.
Antworten
Häufig gestellte Fragen
Was ist hier der Unterschied zwischen einem API-Schlüssel und einem Credential?
Ein API-Schlüssel authentifiziert Ihre Systeme gegenüber CirculeID und ist auf das begrenzt, was Ihre Organisation tun darf. Ein Verifiable Credential authentifiziert einen Dritten — Recycler, Reparaturbetrieb, Behörde — gegenüber einem Pass und entscheidet, welche Stufe er erhält. Schlüssel stellen wir aus; Nachweise kommen von der Stelle, der die Zugriffsrichtlinie vertraut.
Wie sollten Schlüssel begrenzt werden?
Eng und je Dienst. Eine Ausstellungspipeline braucht Schreibzugriff auf Pässe und sonst nichts; ein Shop braucht Lesezugriff auf die öffentliche Stufe und sonst nichts. Begrenzung je Fähigkeit bedeutet, dass ein kompromittierter Schlüssel in einem Dienst keine geschützten Daten eines anderen offenlegt.
Sind Sandbox- und Produktivschlüssel austauschbar?
Nein, bewusst nicht. Schlüssel tragen ihre Umgebung, sodass ein Sandbox-Schlüssel keine Produktivpässe berühren und ein Produktivschlüssel nicht versehentlich in einem Testaufbau verwendet werden kann. Pässe sind langlebige öffentliche Artefakte; eine versehentliche Ausstellung im Produktivbetrieb lässt sich nicht still löschen.
Wie wird die Schlüsselrotation gehandhabt?
Schlüssel können sich überlappen: neuen ausstellen, ausrollen, dann den alten widerrufen — beide sind dazwischen gültig. Rotation ohne Überlappungsfenster bedeutet ein Deployment-Wettrennen, und so kommt es, dass Organisationen am Ende gar nicht rotieren.
Was passiert, wenn ein Schlüssel abfließt?
Widerrufen Sie ihn sofort; der Widerruf wirkt bei der nächsten Anfrage, nicht erst beim Ablauf eines Caches. Das Audit-Log zeigt, was dieser Schlüssel tat, solange er gültig war — genau das, was Sie zur Beurteilung der Exposition brauchen, und der Grund, warum eng begrenzte Schlüssel diese Beurteilung kurz machen.
Next step
Sandbox-Schlüssel holen
Auf eine Fähigkeit begrenzt, in einer Umgebung, die nichts Echtes berühren kann.