Authentication
Deux mécanismes faciles à confondre
Une clé d’API dit quel système appelle. Une attestation vérifiable dit quel niveau un tiers a le droit de lire. Traiter la seconde comme une variante de la première est l’erreur la plus coûteuse d’une intégration passeport.
- Dispositif
- Bearer
- Limité par
- Env + capacité
- Tiers
- Certificats W3C
Definition
Comment s’authentifie-t-on auprès de l’API passeport ?
Vos systèmes présentent une clé porteuse à portée limitée, émise par environnement et par capacité, sur HTTPS. Les tiers qui lisent des niveaux restreints n’utilisent pas de clés du tout : ils présentent un certificat vérifiable W3C émis par une partie à laquelle la politique d’accès fait confiance, et le résolveur renvoie le niveau auquel ce certificat leur donne droit.
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.
Demandes
Présenter une clé
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"]
# }Comparatif
Clés et attestations côte à côte
| 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 |
Pratiques
Ce que nous recommandons
Une clé par service
Ainsi une fuite a un rayon d’impact que vous pouvez décrire en une phrase.
Portées à moindre privilège
Un pipeline d’émission n’a jamais besoin d’un accès en lecture aux niveaux restreints.
Séparation des environnements
Par construction, une clé bac à sable ne peut pas atteindre des passeports de production.
Rotation avec recouvrement
Les deux clés restent valides pendant le changement, si bien que la rotation n’est pas une course au déploiement.
À durée de vie courte lorsque c’est possible
Une expiration sur les clés utilisées par des charges éphémères limite la durée pendant laquelle une fuite compte.
Auditez avant de supposer
Le journal montre ce qu’une clé a fait tant qu’elle était valide — la base pour juger de l’exposition.
Réponses
Questions fréquentes
Quelle est ici la différence entre une clé d’API et un certificat ?
Une clé d’API authentifie vos systèmes auprès de CirculeID et se limite à ce que votre organisation peut faire. Une attestation vérifiable authentifie un tiers — recycleur, réparateur, autorité — auprès d’un passeport et décide du niveau qu’il reçoit. Les clés, c’est nous qui les émettons ; les attestations viennent de qui la politique d’accès reconnaît.
Comment les clés doivent-elles être limitées ?
Étroitement, et par service. Un pipeline d’émission a besoin d’un accès en écriture aux passeports et de rien d’autre ; une boutique a besoin d’un accès en lecture au niveau public et de rien d’autre. Limiter par capacité signifie qu’une clé compromise dans un service n’expose pas les données restreintes d’un autre.
Les clés bac à sable et production sont-elles interchangeables ?
Non, délibérément. Les clés portent leur environnement : une clé bac à sable ne peut pas toucher des passeports de production, et une clé de production ne peut pas être utilisée par accident dans un harnais de test. Les passeports sont des artefacts publics de longue durée ; une émission accidentelle en production ne se supprime pas discrètement.
Comment la rotation des clés est-elle gérée ?
Les clés peuvent se chevaucher : émettez la nouvelle, déployez-la, puis révoquez l’ancienne, les deux étant valides entre-temps. Une rotation sans fenêtre de recouvrement est une course au déploiement, et c’est ainsi que des organisations finissent par ne jamais tourner leurs clés.
Que se passe-t-il si une clé fuite ?
Révoquez-la immédiatement ; la révocation prend effet à la requête suivante et non à l’expiration d’un cache. Le journal d’audit montre ce que cette clé a fait tant qu’elle était valide, ce dont vous avez besoin pour juger l’exposition — et la raison pour laquelle des clés étroitement limitées rendent ce jugement court.
Next step
Obtenir une clé bac à sable
Limitée à une seule capacité, dans un environnement qui ne peut toucher à rien de réel.