Authentication
Dos mecanismos fáciles de confundir
Una clave de API dice qué sistema llama. Una credencial verificable dice qué nivel tiene derecho a leer un tercero. Tratar la segunda como una variante de la primera es el error más caro de una integración de pasaporte.
- Sistema
- Bearer
- Acotado por
- Entorno + capacidad
- Terceros
- Credenciales del W3C
Definition
¿Cómo se autentica uno contra la API del pasaporte?
Sus sistemas presentan por HTTPS una clave portadora con alcance limitado, emitida por entorno y por capacidad. Los terceros que leen niveles restringidos del pasaporte no usan claves en absoluto: presentan una credencial verificable del W3C emitida por una parte en la que confía la política de acceso, y el resolutor devuelve el nivel al que esa credencial les da derecho.
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.
Solicitudes
Presentar una clave
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"]
# }Comparativa
Claves y credenciales, una junto a otra
| 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 |
Prácticas
Qué recomendamos
Una clave por servicio
Así una fuga tiene un radio de impacto que puede describir en una frase.
Ámbitos de mínimo privilegio
Una tubería de emisión nunca necesita acceso de lectura a los niveles restringidos.
Separación de entornos
Por construcción, una clave de sandbox no puede alcanzar pasaportes de producción.
Rotación con solape
Ambas claves son válidas durante el cambio, de modo que la rotación no es una carrera de despliegue.
De vida corta cuando sea posible
Una caducidad en las claves usadas por cargas efímeras limita cuánto tiempo importa una fuga.
Audite antes de suponer
El registro muestra qué hizo una clave mientras era válida: la base para juzgar la exposición.
Respuestas
Preguntas frecuentes
¿Cuál es aquí la diferencia entre una clave de API y una credencial?
Una clave de API autentica sus sistemas ante CirculeID y está acotada a lo que su organización puede hacer. Una credencial verificable autentica a un tercero —reciclador, reparador, autoridad— ante un pasaporte y decide qué nivel recibe. Las claves las emitimos nosotros; las credenciales vienen de quien la política de acceso reconozca.
¿Cómo deben acotarse las claves?
De forma estrecha y por servicio. Una tubería de emisión necesita acceso de escritura a pasaportes y nada más; una tienda necesita acceso de lectura al nivel público y nada más. Acotar por capacidad significa que una clave comprometida en un servicio no expone datos restringidos de otro.
¿Son intercambiables las claves de sandbox y producción?
No, deliberadamente. Las claves llevan su entorno, así que una clave de sandbox no puede tocar pasaportes de producción y una de producción no puede usarse por accidente en un banco de pruebas. Los pasaportes son artefactos públicos de larga vida; una emisión accidental en producción no es algo que se borre discretamente.
¿Cómo se gestiona la rotación de claves?
Las claves pueden solaparse: emita la nueva, despliéguela y luego revoque la antigua, con ambas válidas en el intervalo. Rotar sin ventana de solape es una carrera de despliegue, y así es como las organizaciones acaban no rotando nunca.
¿Qué ocurre si se filtra una clave?
Revóquela de inmediato; la revocación surte efecto en la siguiente petición y no al expirar una caché. El registro de auditoría muestra qué hizo esa clave mientras fue válida, que es lo que necesita para juzgar la exposición, y la razón por la que acotar bien las claves hace corto ese juicio.
Next step
Obtener una clave de sandbox
Acotada a una sola capacidad, en un entorno que no puede tocar nada real.