Provisioning por key claim

El key claim es el flujo para el autoaprovisionamiento a escala. En lugar de registrar cada dispositivo a mano, tú (o tu fabricante por contrato) grabas una provisioning key compartida en un lote de dispositivos. En el primer arranque, cada dispositivo llama a POST /api/v1/provision con esa key, y la plataforma crea el dispositivo y devuelve sus credenciales. No hay ningún operador en el bucle en el momento del claim.

Este es el flujo adecuado cuando los dispositivos salen de una línea y deben conectarse por su cuenta. Para dispositivos puntuales, registro manual es más sencillo.

Paso 1 — Crear una plantilla / key de provisioning

Un admin del tenant crea una plantilla de provisioning (y la key que emite) con antelación. La plantilla acota lo que la key puede hacer:

Campo	Propósito
Referencia de profile	El device profile que heredan los nuevos dispositivos (tags, configuración, política de anchoring, esquema de telemetry, …)
Patrón de hardware_id permitido	Restringe qué hardware IDs pueden reclamar con esta key
Caducidad	Instante UTC tras el cual se rechaza la key (sin caducidad si no se establece)
Flag de un solo uso	Si se establece, la key se marca como usada tras un claim exitoso
Tipo de credencial	Qué credencial reciben los nuevos dispositivos (API key, PSK o cert)
Grupos por defecto	Grupos a los que se une cada dispositivo reclamado con esta key

La key está vinculada a un tenant. El tenant del dispositivo provisionado siempre se deriva de la key — nunca de nada que el dispositivo envíe.

Nota

La plataforma almacena solo el hash SHA-256 de la provisioning key (junto con su tenant, nombre, estado y caducidad). La key en bruto se muestra una vez en la creación; distribúyela de forma segura a la fábrica y trátala como el secreto que es.

Paso 2 — El dispositivo reclama su identidad

En el primer arranque el dispositivo envía su provisioning key en bruto, un nombre legible y su hardware_id estable a POST /api/v1/provision.

POST /api/v1/provision HTTP/1.1
Host: api.kronoxdata.com
Content-Type: application/json

{
  "provision_key": "pk_factory_7Qx2mZr8K...redacted...",
  "device_name": "Cold Store Sensor 014",
  "hardware_id": "AA:BB:CC:00:11:22"
}

Nota

No hay campo tenant_id en esta petición, por diseño. El tenant se deriva de la key validada. Un dispositivo no puede pedir que se le coloque en un tenant — solo puede demostrar de qué tenant es la key que posee.

La misma llamada por curl:

curl -sS -X POST https://api.kronoxdata.com/api/v1/provision \
  -H "Content-Type: application/json" \
  -d '{
    "provision_key": "pk_factory_7Qx2mZr8K...redacted...",
    "device_name": "Cold Store Sensor 014",
    "hardware_id": "AA:BB:CC:00:11:22"
  }'

Primer claim exitoso

Un dispositivo totalmente nuevo recibe de vuelta su device_id de la plataforma y una api_key recién acuñada:

{
  "device_id": "8f1c0b7e-3d2a-4f56-9a10-2c4e6f8b1d33",
  "api_key": "sk_live_Zr8K2mQx...redacted..."
}

Peligro

La api_key se devuelve exactamente una vez. Persístela en el dispositivo de inmediato — la plataforma solo almacena un hash y no puede volver a mostrarla. Si el dispositivo la pierde, debes rotar a una nueva key.

El dispositivo ahora descarta la provisioning key y autentica todas las peticiones futuras con sk_live_…. Ver credenciales para las cabeceras de autenticación.

Reclamo idempotente

Si ya existe en el tenant un dispositivo con el mismo hardware_id, la llamada es idempotente: devuelve el device_id existente y una api_key vacía.

{
  "device_id": "8f1c0b7e-3d2a-4f56-9a10-2c4e6f8b1d33",
  "api_key": ""
}

Una api_key vacía no es un error — es la plataforma diciendo “ya conozco este dispositivo; sigue usando la key que se te emitió antes”. No se crea ningún dispositivo duplicado, no se acuña una segunda key y no se emite ningún evento device.provisioned. Por tanto, los dispositivos deben almacenar de forma duradera su primera API key emitida y no depender de obtener una nueva al reiniciar.

Consejo

Diseña tu firmware para que volver a reclamar sea seguro: intenta provisionar y, si la api_key de la respuesta está vacía, recurre a la key que ya está en el almacenamiento seguro. Esto hace que la ruta de arranque sea resistente a reintentos, borrados de flash que preservan la key y problemas de red.

El flujo de claim completo

sequenceDiagram
  autonumber
  participant Dev as Dispositivo
  participant GW as Gateway / device-link
  participant Reg as Device registry
  participant Auth as Servicio de autenticación

  Dev->>GW: POST /api/v1/provision<br/>{provision_key, device_name, hardware_id}
  GW->>GW: SHA-256(provision_key)
  GW->>GW: Buscar key por hash,<br/>comparación de tiempo constante,<br/>comprobar estado + caducidad
  Note over GW: Inválida / deshabilitada / caducada →<br/>PermissionDenied (uniforme)
  GW->>Reg: CreateDevice(tenant_from_key, name, hardware_id)
  alt Nuevo hardware_id
    Reg-->>GW: device_id (creado)
    GW->>Auth: MintAPIKey(tenant, device_id)
    Auth-->>GW: sk_live_… (raw, una vez)
    GW-->>Dev: {device_id, api_key}
    GW--)Reg: publicar evento device.provisioned
  else hardware_id existente (idempotente)
    Reg-->>GW: device_id (existente)
    GW-->>Dev: {device_id, api_key: ""}
  end

Propiedades de seguridad

Precaución

La ruta de claim está construida para que una key filtrada o adivinada revele lo menos posible:

• La key en bruto nunca se persiste. Solo se almacena su hash SHA-256, y la key en bruto nunca se registra en logs.
• Comparación de tiempo constante. El hash almacenado se compara con un hash recién calculado de la key presentada usando una comparación de tiempo constante, de modo que el tiempo no puede usarse para recuperar la key.
• Tenant derivado de la key. El tenant del dispositivo proviene únicamente de la key validada — nunca de ningún campo suministrado por el cliente. Un dispositivo no puede elegir su tenant.
• Error uniforme. Las keys desconocidas, deshabilitadas y caducadas devuelven todas el mismo PermissionDenied (“invalid provisioning key”). Quien invoca no puede distinguir los tres estados, así que las keys válidas no pueden enumerarse.
• Credenciales idempotentes de una sola emisión. Un reclamo nunca acuña una segunda key, lo que evita la proliferación accidental de credenciales por reintentos.

Relacionado

Device profiles Los valores por defecto y políticas que un dispositivo reclamado hereda vía la referencia de profile de la plantilla.

Identidad y credenciales de dispositivo Qué es la API key devuelta, cómo presentarla y cómo rotarla.

Importación masiva Genera provisioning keys para un lote de fábrica completo, luego reclama según este flujo.

Registro manual Registra un solo dispositivo directamente cuando el autoaprovisionamiento es excesivo.