Traducción. Autoritativo: fs-idn-0006-api-keys.md.
Contexto
Una API key es lo primero que toca un integrador, y su validación está en el camino caliente de Runtime: cada llamada atrack la paga. Tiene que ser rápida y tiene que ser segura, y eso tira en
direcciones opuestas.
DEC-D5 elimina la complicación habitual: una key es un sujeto con asignaciones de rol, no una
cosa con su propio lenguaje de scopes. La misma resolución y la misma verificación sirven a una
persona y a una máquina, así que no hay un segundo camino de autorización que pueda separarse.
DEC-D6 elimina otra: a los terceros nunca se les exige entregar rangos de IP. Key más HMAC más
rate limits es el modelo de seguridad; la allowlist de IP existe como endurecimiento opcional,
apagada por defecto, porque exigir IPs a un integrador que corre en la nube de otro es pedir algo
que no puede dar.
Alcance (normativo)
identity.api_keyscon secreto hasheado y prefijo en claro para identificación.- Asignación de roles a una key, por el mismo mecanismo que a un usuario.
- Rotación con ventana de solapamiento para que ningún request falle durante el cambio.
last_used_aty última IP usada, para detección.- Expiración opcional.
- Write keys públicas para ingesta desde el navegador (F1b, con el widget).
Fuera de alcance (normativo)
- Clientes OAuth2 — FS-IDN-0007. Una key la emite el tenant para sí mismo; un cliente OAuth se lo otorga el tenant a otro.
- El modelo de permisos — FS-IDN-0002.
- Allowlist de IP por tenant, una feature posterior de política de seguridad.
Comportamiento (normativo)
- Una key se muestra exactamente una vez, al crearla. Se guarda hasheada y no se puede recuperar — perderla significa rotarla, y ese es el canje correcto.
- Toda key lleva un prefijo en claro (
sk_live_a1b2…). Una key encontrada en un repositorio público se identifica y revoca desde el prefijo, sin que nadie tenga el secreto. - Una key es un sujeto con asignaciones de rol. No hay lenguaje de scopes específico de keys, y la verificación es el mismo camino de código que para un usuario.
- La rotación emite un secreto nuevo y mantiene el viejo válido durante una ventana de solapamiento configurable, 24 horas por defecto. Una rotación que rompe producción es una rotación que nadie ejecuta, y una key que nadie rota es el riesgo real.
- La validación se cachea y hace cero consultas en el camino caliente con la caché tibia. La revocación invalida la caché de inmediato.
last_used_aty la última IP se registran de forma asíncrona, nunca en el camino del request.- Las keys pueden tener expiración opcional, con aviso anticipado a quien la creó.
- Crear o rotar una key exige reautenticación (FS-IDN-0004) y escribe una fila de auditoría.
- Una key pertenece a una organización y jamás puede actuar sobre otra, lleve los roles que lleve.
- Las write keys públicas (F1b) son un tipo distinto: solo ingesta de track, seguras de embeber en un bundle de navegador, con rate limit más duro y acotadas a orígenes configurados. Nunca reciben otro permiso.
- PROHIBIDO: una key en un log, un payload de evento, un mensaje de error o un query param.
Datos (normativo)
API (normativo)
El listado nunca devuelve un secreto, solo prefijos y metadata.
Eventos (normativo)
identity.api_key.created, .rotated y .revoked, con el prefijo y el actor — nunca el secreto.
Criterios de aceptación (normativo)
- Una key se devuelve exactamente una vez; toda lectura posterior devuelve solo su prefijo.
- Durante el solapamiento autentican el secreto viejo y el nuevo; después, solo el nuevo.
- La validación hace cero consultas con la caché tibia, verificado con un contador de consultas.
- La revocación es efectiva en el siguiente request.
- Una key de la organización A no puede actuar sobre la B bajo ningún rol.
- Una write key pública solo alcanza la ingesta de track; todo otro endpoint la rechaza.
last_used_atse actualiza sin agregar latencia medible al request.- Crear una key sin reautenticación se rechaza.
- Negativo: ningún secreto aparece en logs, eventos, errores ni URLs.