Rotación y revocación de credenciales

Cada credencial de dispositivo —una API key, una PSK o un certificado de cliente X.509— tiene un ciclo de vida. La rotación reemplaza una credencial mientras el dispositivo sigue funcionando; la revocación anula una credencial en el instante en que crees que está comprometida. Las dos son deliberadamente operaciones distintas con garantías distintas, y elegir la correcta importa: rota cuando una credencial simplemente es antigua, revoca cuando se ha filtrado.

Esta página cubre los flujos de API key y PSK. Para ver cómo se emiten y presentan las credenciales por primera vez, consulta Identidad y credenciales del dispositivo.

El ciclo de vida de la credencial

Una credencial pasa por un pequeño conjunto de estados. La rotación y la revocación son las dos transiciones que tú impulsas como operador.

stateDiagram-v2
  [*] --> active : emitida en el provisioning
  active --> overlapping : rotar (nueva key emitida)
  overlapping --> active : termina ventana de solapamiento\n(key antigua rechazada)
  active --> revoked : revocar (inmediato)
  overlapping --> revoked : revocar (inmediato)
  revoked --> [*]

• active — la credencial autentica con normalidad. Un dispositivo tiene exactamente una credencial activa por tipo en estado estable.
• overlapping — hay una rotación en curso. Tanto la credencial antigua como la nueva autentican. Esta ventana existe para que el dispositivo pueda adoptar la nueva credencial según su propio calendario sin un hueco en la conectividad.
• revoked — la credencial está muerta. Toda petición futura que la use devuelve UNAUTHENTICATED, y cualquier sesión de protocolo activa que haya autenticado se cierra donde el transporte lo permita.

Nota

El valor de una credencial se muestra exactamente una vez, en el momento en que se emite — tanto en el provisioning como en la rotación. CORE-M almacena solo un hash, un prefijo y metadatos. Si pierdes una key recién rotada antes de que el dispositivo la adopte, rota de nuevo en lugar de intentar recuperarla.

Rotación con una ventana de solapamiento

El objetivo central de la rotación es cero tiempo de inactividad. Cuando rotas, CORE-M:

1. Genera una credencial nueva y la devuelve una vez.
2. Mantiene válida la credencial antigua durante una ventana de solapamiento configurada.
3. Rechaza la credencial antigua en cuanto termina la ventana.

Durante la ventana de solapamiento ambas credenciales autentican, así que un dispositivo puede obtener y aplicar su nueva credencial según su propio calendario —en el siguiente arranque, en un sondeo de mantenimiento, o enviada vía device RPC— sin presentar nunca una inválida. Configura la ventana más larga que el peor caso de intervalo de check-in de tu dispositivo.

timeline
  title Cronología de rotación de API key
  Rotate issued : K1 active : K2 issued (returned once)
  Overlap window : K1 valid : K2 valid
  Window ends : K1 rejected : K2 active

Rotar una API key

1. Rota la credencial. Como admin del tenant (o un token con el scope devices:write), llama al endpoint de rotación para el dispositivo. Indica la ventana de solapamiento en segundos.

   curl -X POST https://api.kronoxdata.com/api/v1/devices/dev_8f3a/credentials/rotate \
     -H "Authorization: Bearer <tenant-admin-jwt>" \
     -H "Content-Type: application/json" \
     -d '{
       "credential_type": "api_key",
       "overlap_seconds": 86400
     }'

2. Captura la nueva key de la respuesta. Se devuelve una vez. El prefijo de la key antigua se incluye para que puedas confirmar qué credencial se está retirando.

   {
     "device_id": "dev_8f3a",
     "credential_type": "api_key",
     "new_api_key": "sk_live_9Qk3pR2wXn7vJ4mB...",
     "new_prefix": "sk_live_9Qk3",
     "previous_prefix": "sk_live_2Ab7",
     "overlap_expires_at": "2026-05-30T12:00:00Z"
   }

3. Entrega la nueva key al dispositivo. Envíala como sea que tu flota recoja la configuración — un atributo compartido, una RPC o el propio sondeo programado del dispositivo. Hasta que el dispositivo cambie, sigue autenticando con la key antigua.

4. Deja que la ventana se cierre. En overlap_expires_at la key antigua (sk_live_2Ab7…) deja de autenticar y devuelve UNAUTHENTICATED. No se necesita ninguna otra acción.

Se escribe un evento de auditoría device.credential.rotated por cada rotación, registrando el actor, el dispositivo y los prefijos de la credencial — nunca la key en bruto.

Rotar una PSK

Las claves precompartidas (usadas por dispositivos CoAP/DTLS y LwM2M) rotan de la misma forma. La diferencia está solo en el tipo de credencial y en lo que el dispositivo debe reconfigurar en su pila DTLS.

curl -X POST https://api.kronoxdata.com/api/v1/devices/dev_8f3a/credentials/rotate \
  -H "Authorization: Bearer <tenant-admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_type": "psk",
    "overlap_seconds": 172800
  }'

{
  "device_id": "dev_8f3a",
  "credential_type": "psk",
  "psk_identity": "dev_8f3a",
  "new_psk": "3f9c1d7a8b2e4f60a1c5d9e2f7b3a4c6...",
  "overlap_expires_at": "2026-05-31T12:00:00Z"
}

Precaución

Una sesión DTLS se establece en el momento del handshake. Un dispositivo que ya está conectado con la PSK antigua mantiene su sesión hasta su siguiente reconexión — la ventana de solapamiento cubre exactamente ese hueco. Haz que la ventana de solapamiento de la PSK sea cómodamente más larga que la vida útil de tu sesión DTLS, de modo que un dispositivo que se reconecte a mitad de rotación siempre tenga a mano una key válida.

Revocación inmediata

La revocación es para el mal día: una key subida a un repositorio público, un dispositivo robado, un contratista que se fue. No hay ventana de solapamiento — la credencial se rechaza de inmediato.

1. Revoca la credencial. Identifícala por prefijo (la revocación nunca necesita el valor en bruto).

   curl -X POST https://api.kronoxdata.com/api/v1/devices/dev_8f3a/credentials/revoke \
     -H "Authorization: Bearer <tenant-admin-jwt>" \
     -H "Content-Type: application/json" \
     -d '{
       "credential_type": "api_key",
       "prefix": "sk_live_2Ab7"
     }'

2. Los efectos son inmediatos. A partir de este punto:

   • Toda petición que use la credencial revocada devuelve UNAUTHENTICATED.
   • Las sesiones de protocolo activas autenticadas con ella se desconectan donde el transporte lo permita (un cliente MQTT se descarta, una sesión DTLS se cierra).
   • Se publica el evento profile.credential.revoked.{tenant}.{device} para que los consumidores downstream (alertas, paneles) reaccionen en tiempo real.

3. Re-credencia el dispositivo. Un dispositivo revocado no puede enviar telemetry hasta que tenga una credencial nueva. O bien rota un reemplazo (si una credencial de un par sigue siendo buena) o reaprovisiona el dispositivo para emitir una nueva.

Peligro

La revocación no tiene periodo de gracia por diseño. Si el dispositivo sigue en campo y revocas su única credencial, queda a oscuras hasta que le des una nueva. Cuando el dispositivo es de confianza y simplemente quieres retirar una key antigua, rota — no revoques.

Rotar vs revocar: ¿cuál?

Situación	Usa	Por qué
La credencial es antigua / superó la edad de tu política de rotación	Rotar	Sin tiempo de inactividad; el dispositivo migra durante la ventana de solapamiento.
Higiene de keys programada y rutinaria	Rotar	La ventana de solapamiento absorbe el tiempo del check-in.
Key filtrada, dispositivo robado, sospecha de compromiso	Revocar	Corta al atacante de inmediato, sesiones incluidas.
Dar de baja un dispositivo definitivamente	Revocar	No hay razón para mantener válida ninguna credencial.

Cuándo y por qué rotar

• Según un calendario. Establece una edad máxima de credencial en la política de credenciales de tu device profile y rota antes de que expire. La rotación rutinaria limita el radio de impacto de una key que aún no sabes que se ha filtrado.
• Ante un cambio de personal o de infraestructura. Rota después de que alguien con acceso al material de provisioning se marche, o después de migrar los sistemas que guardan keys.
• Tras un casi-incidente. Una key que podría haberse expuesto pero donde el dispositivo sigue siendo de confianza: rota con un solapamiento corto, luego confirma que el prefijo antiguo deja de aparecer en los metadatos de last_used antes de considerarla limpia.

Consejo

Los tokens de API con scope y las cuentas de servicio (para integraciones de backend, no dispositivos) rotan con el mismo modelo de ventana de solapamiento. Consulta Seguridad y cumplimiento para scopes de token, listas de IP permitidas y el rastro de auditoría.

A dónde ir después

Relacionado

• Identidad y credenciales del dispositivo — cómo se emiten y presentan por primera vez las API keys, PSKs y certificados.
• Seguridad y cumplimiento — scopes de token, registro de auditoría y eventos de revocación.
• Device RPC — una forma de enviar una credencial rotada a un dispositivo bajo demanda.