Identidad y credenciales del dispositivo

Cada dispositivo en CORE-M tiene dos identificadores y exactamente un tipo de credencial activa. Entender la diferencia es la base del provisioning y de la rotación de credenciales.

Dos identificadores: device_id vs hardware_id

	device_id	hardware_id
Qué es	UUID asignado por la plataforma	Número de serie del fabricante, dirección MAC u otro identificador de hardware estable
Quién lo establece	CORE-M, en el registro	Tú, a partir del hardware
Unicidad	Único a nivel global	Único dentro de un tenant
¿Mutable?	Nunca	Tratado como inmutable — es el ancla de idempotencia
Se usa para	Todas las rutas y búsquedas de la API (p. ej. /api/v1/devices/{device_id})	Deduplicación y (re)provisioning idempotente

El device_id es lo que usas en todas partes en la API. El hardware_id existe para que la plataforma pueda reconocer el mismo dispositivo físico entre reintentos: registrar o aprovisionar dos veces con el mismo hardware_id devuelve el dispositivo existente en lugar de crear un duplicado.

Precaución

El hardware_id es único por tenant, no a nivel global. Dos tenants distintos pueden ambos tener un dispositivo con el hardware_id AA:BB:CC:00:11:22 — son dispositivos distintos. Dentro de un mismo tenant, un hardware_id duplicado en el registro manual se rechaza con ALREADY_EXISTS.

Credenciales: cómo se autentica un dispositivo

Los dispositivos se autentican ante CORE-M con uno de tres tipos de credencial. Elige el que coincida con tu protocolo y tu modelo de amenazas.

Credencial	Emitida por	Almacenada en reposo como	Presentada como
API key	Provisioning o CreateAPIKey; devuelta en bruto una vez	Hash SHA-256 (la key en bruto nunca se almacena)	Authorization: Bearer sk_live_… o X-API-Key: sk_live_…
PSK (clave precompartida)	Generada/asignada en el provisioning, ≥ 32 bytes	De forma segura en la plataforma; aprovisionada al dispositivo	Handshake DTLS PSK (CoAP, LwM2M)
Certificado de cliente X.509	Tu CA; el certificado público se registra vía RegisterDeviceCert	Solo el fingerprint SHA-256 de los bytes DER	Certificado de cliente mTLS (MQTT, CoAP, LwM2M)

Precaución

Los usuarios del panel se autentican con JWTs firmados con Ed25519 (token de acceso de 15 minutos, refresh de 7 días). Los dispositivos nunca usan JWTs. Un dispositivo presenta una API key, una PSK o un certificado de cliente X.509 — nada más. Si te ves poniendo la credencial de un dispositivo en un JWT, algo está mal.

API key

La credencial de dispositivo más común. Formato:

sk_live_ + URL-safe encoding of 32 random bytes

La plataforma almacena solo un hash de la key. El valor en bruto se devuelve exactamente una vez —en el provisioning o cuando creas la key— y no se puede recuperar de nuevo. Si se pierde, rótala por una nueva.

Preséntala en cada petición usando cualquiera de las dos cabeceras:

Authorization: Bearer

POST /api/v1/devices/{device_id}/uplink HTTP/1.1
Host: api.kronoxdata.com
Authorization: Bearer sk_live_Zr8K2mQx...redacted...
Content-Type: application/json

{"kind":"telemetry","payload":"..."}

X-API-Key

POST /api/v1/devices/{device_id}/uplink HTTP/1.1
Host: api.kronoxdata.com
X-API-Key: sk_live_Zr8K2mQx...redacted...
Content-Type: application/json

{"kind":"telemetry","payload":"..."}

El middleware de auth resuelve la key a su tenant_id y device_id y los inyecta en el contexto de la petición. El dispositivo nunca envía su propio tenant_id — la identidad se deriva de la credencial, así que una key robada no puede suplantar al dispositivo de otro tenant.

Consejo

Usa Authorization: Bearer donde puedas — es la forma estándar y funciona con la mayoría de las librerías de cliente HTTP y MQTT listas para usar. X-API-Key existe para clientes que reservan la cabecera Authorization para otra cosa.

PSK (clave precompartida)

Un secreto simétrico de al menos 32 bytes, usado para el handshake DTLS en transportes UDP. Ideal para dispositivos restringidos sobre CoAP o LwM2M donde ejecutar una pila de certificados completa es demasiado pesado. La PSK se genera o asigna durante el provisioning y se graba en el dispositivo junto a su identidad. Trátala como cualquier otro secreto: otorga el mismo acceso que una API key.

Certificado de cliente X.509

La credencial de dispositivo más fuerte, usada para TLS mutuo (mTLS) sobre MQTT, CoAP y LwM2M. Emites el certificado desde tu propia CA y registras solo el certificado público con la plataforma vía RegisterDeviceCert (POST /api/v1/devices/{device_id}/certs). CORE-M parsea el PEM del lado del servidor y almacena solo el fingerprint SHA-256 de los bytes DER — ese fingerprint es el ancla de identidad para las búsquedas mTLS.

Peligro

Nunca envíes la clave privada de un dispositivo a la plataforma. RegisterDeviceCert acepta solo el PEM del certificado público. La clave privada permanece en el dispositivo. Registrar una clave privada sería un compromiso crítico.

Para dejar de confiar en un certificado, revócalo por fingerprint con RevokeDeviceCert (DELETE /api/v1/devices/certs/{fingerprint}). Lista los certificados de un tenant con ListDeviceCerts (GET /api/v1/devices/certs, opcionalmente filtrado por device_id).

Rotación y revocación

Las credenciales no son para siempre. Dos operaciones las mantienen seguras:

• Rotar — emitir una credencial nueva y retirar la antigua. Para las API keys, la nueva key se devuelve una vez; la key antigua sigue funcionando durante una ventana de solapamiento configurada para que el dispositivo pueda cambiar sin tiempo de inactividad, tras lo cual deja de aceptarse.
• Revocar — anular una credencial de inmediato. Las peticiones futuras que usen una API key o un certificado revocados devuelven UNAUTHENTICATED, y las sesiones de protocolo activas autenticadas con ella se desconectan donde el transporte lo permita.

Nota

Rota según un calendario; revoca ante la sospecha de compromiso. La rotación tiene una ventana de solapamiento para que los dispositivos sigan en línea; la revocación es inmediata y no tiene periodo de gracia.

De dónde vienen las credenciales

No acuñas credenciales a mano — se emiten como parte de un flujo de provisioning:

Provisioning por reclamación de clave Los dispositivos se autorregistran en campo con una clave precompartida y reciben una API key en la respuesta.

Registro manual Registra un dispositivo como admin y recibe su API key (mostrada una vez).

Importación masiva Genera claves de provisioning para todo un lote de fábrica desde un CSV.

Device profiles Una política de credenciales en un profile decide qué tipo de credencial reciben los dispositivos nuevos.