Registro manual

El registro manual crea un solo dispositivo directamente, como un admin autenticado. Es la forma más sencilla de poner un dispositivo en línea cuando no necesitas un flujo de autoaprovisionamiento — un dispositivo de laboratorio, una integración puntual o el primer dispositivo que conectas mientras aprendes la plataforma.

La operación es DeviceRegistryService.RegisterDevice, expuesta como POST /api/v1/devices.

Quién puede invocarla

Esta es una operación de admin/dashboard, autenticada con el JWT Ed25519 de un usuario del dashboard — no con una credencial de dispositivo. Quien la invoca debe ser un tenant_admin (o platform_admin) del tenant, o un member con el permiso devices. El tenant se toma del JWT, nunca del cuerpo de la petición.

Nota

Los dispositivos no se registran a sí mismos a través de este endpoint — no tienen JWT. Para el autorregistro impulsado por el dispositivo, usa provisioning por key claim.

Campos de la petición

Campo	Obligatorio	Descripción
name	sí	Nombre legible del dispositivo
hardware_id	sí	Identificador de hardware estable; único dentro del tenant
groups	no	Nombres de grupos a los que se une el dispositivo
tags	no	Tags clave/valor para filtrado y organización
anchor_mode	no	Modo de anchoring en blockchain (ANCHOR_MODE_MERKLE_BATCH por defecto, ANCHOR_MODE_PER_EVENT, ANCHOR_MODE_HASH_CHAIN)
profile_id	no	Device profile del que heredar los valores por defecto
gateway_id	no	device_id de un gateway padre, si este es un dispositivo hijo
firmware	no	Cadena de versión de firmware inicial
meta	no	Metadatos clave/valor de forma libre
config	no	Configuración de estado deseado entregada al dispositivo

Consejo

Establece profile_id y deja que el profile lleve los tags, la configuración, la política de anchoring y el esquema de telemetry. Los campos explícitos de esta petición anulan los valores por defecto del profile donde está permitido — ver orden de herencia.

Ejemplo

curl -sS -X POST https://api.kronoxdata.com/api/v1/devices \
  -H "Authorization: Bearer <DASHBOARD_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lab Bench Thermometer",
    "hardware_id": "HW-LAB-0001",
    "groups": ["lab", "floor-3"],
    "tags": { "region": "eu", "owner": "qa" },
    "anchor_mode": "ANCHOR_MODE_MERKLE_BATCH",
    "profile_id": "p_temp_sensor_v2"
  }'

Precaución

La cabecera Authorization: Bearer aquí lleva un JWT del dashboard, no una API key de dispositivo sk_live_…. Se parecen superficialmente pero son credenciales diferentes para quienes invocan diferentes — los admins registran dispositivos, los dispositivos envían telemetry.

Respuesta

RegisterDevice devuelve el registro completo del dispositivo, incluyendo su device_id generado y una credencial de provisioning (una api_key, o un certificado de cliente según la política de credenciales):

{
  "device_id": "3a9f1d22-6b4c-4e8a-bf21-90c7e5d4a118",
  "tenant_id": "11111111-1111-1111-1111-111111111111",
  "name": "Lab Bench Thermometer",
  "hardware_id": "HW-LAB-0001",
  "status": "registered",
  "groups": ["lab", "floor-3"],
  "tags": { "region": "eu", "owner": "qa" },
  "anchor_mode": "ANCHOR_MODE_MERKLE_BATCH",
  "profile_id": "p_temp_sensor_v2",
  "api_key": "sk_live_Zr8K2mQx...redacted...",
  "created_at": "2026-05-29T10:15:00Z"
}

Peligro

La api_key se muestra una vez en esta respuesta. Cópiala al dispositivo ahora — la plataforma solo almacena un hash y no puede devolverla de nuevo. Si la pierdes, rota a una nueva key en lugar de volver a registrar.

En caso de éxito la plataforma también publica un evento device.registered para los servicios posteriores.

hardware_id duplicado

hardware_id es único dentro de un tenant. Registrar un segundo dispositivo con un hardware_id que ya existe en el tenant se rechaza:

{
  "code": "ALREADY_EXISTS",
  "message": "device with hardware_id \"HW-LAB-0001\" already exists in this tenant"
}

No se crea ningún dispositivo y no se publica ningún evento. Esto difiere de key claim, que trata un hardware_id repetido como un reclamo idempotente del dispositivo existente en lugar de un error. La distinción es intencionada: un admin que registra a mano casi siempre lo entiende como un dispositivo nuevo, así que un choque se hace notar con fuerza; un dispositivo que reinicia y vuelve a reclamar significa “soy yo otra vez”, así que tiene éxito en silencio.

Cuándo usar esto frente a key claim

Usa registro manual cuando…	Usa key claim cuando…
Tienes un puñado de dispositivos	Tienes un lote de fábrica o una flota
Hay un admin/operador en el bucle	Los dispositivos deben conectarse sin supervisión
Quieres tener el registro del dispositivo configurado antes de que el hardware se envíe	El hardware se autorregistra en el primer arranque
Estás probando o integrando un dispositivo	Estás desplegando a escala

Para lotes, genera keys con importación masiva y deja que los dispositivos se reclamen a sí mismos.

Relacionado

Device profiles Establece profile_id para heredar tags, configuración, anchoring y los valores por defecto del esquema.

Identidad y credenciales de dispositivo Qué es la API key devuelta y cómo la presenta el dispositivo.

Provisioning por key claim La alternativa sin supervisión y a escala al registro manual.