Sesiones de usuarios de dispositivos

Cómo funciona

Utilice estos endpoints cuando una aplicación suya autentique a sus propios usuarios en un dispositivo administrado. La aplicación identifica el dispositivo por su número de serie, por ejemplo, uno transmitido en su configuración administrada. Cuando un usuario inicia sesión, su backend reporta el inicio de sesión con ese número de serie y su propio id de usuario, y conserva el loginId devuelto. Cuando el usuario cierra sesión, su backend reporta el cierre de sesión.

El primer inicio de sesión de un externalUserId crea un Usuario de dispositivo con auth EXTERNAL. Los inicios de sesión posteriores del mismo externalUserId reutilizan ese usuario, y un userName que difiera de su nombre actual lo renombra. También puede reportar el inicio de sesión de un Usuario de dispositivo existente con cualquier auth mediante su deviceUserId.

GET /device-user-logins devuelve las sesiones de usuarios de dispositivos de la empresa, las más recientes primero: aquellas que reporta su sistema y los inicios de sesión mediante PIN y SSO que el agente de Nomid reporta desde el dispositivo. loginSource y logoutSource indican quién reportó cada mitad de una sesión.

Una sesión reportada a través de la API no caduca en Nomid: permanece abierta hasta que usted reporte su cierre de sesión. Cada llamada de inicio de sesión registra una nueva sesión, incluso si el mismo usuario ya ha iniciado sesión en ese dispositivo.

La API solo cierra las sesiones que se reportaron a través de la API. El dispositivo cierra los inicios de sesión por PIN o SSO en el agente de Nomid.

Requisitos

• GET /device-user-logins requiere DEVICES_READ, al igual que las demás lecturas de dispositivos.
• Reportar inicios y cierres de sesión de usuarios de dispositivos (POST /device-user-logins y POST /device-user-logins/logout) requiere DEVICES_COMMAND, el permiso que envía comandos a los dispositivos; una clave solo lo obtiene junto con DEVICES_READ. Las sesiones de usuarios de dispositivos no tienen un permiso propio.
• Para reportar un inicio de sesión, el activo debe tener un dispositivo administrado, es decir, un dispositivo inscrito en Nomid actualmente.
• La clave validada selecciona la empresa; las solicitudes no tienen ningún parámetro de tenant o empresa. Los endpoints de inicio y cierre de sesión pueden dirigirse a todos los activos de la empresa.

Endpoints

Las rutas son relativas a la URL base de la API y requieren el encabezado X-API-Key.

https://api.nomid.tech/emm/api/v1

Listar sesiones

Todos los parámetros de consulta son opcionales. Sin filtros, el endpoint devuelve las últimas sesiones de la empresa.

Las sesiones de un activo incluyen las registradas en inscripciones anteriores del mismo hardware, con el mismo número de serie, por lo que un dispositivo reinscrito conserva su historial. Un activo desconocido devuelve un 404 con el código asset_not_found; un deviceUserId o externalUserId desconocido no coincide con ninguna sesión y devuelve una lista vacía.

Notificar un inicio de sesión

Envíe un campo de dispositivo y un campo de usuario. Enviar ambos o ninguno de un par devuelve 400.

Conserve el loginId de la respuesta: es el comprobante que cierra exactamente esta sesión. Si se pierde una respuesta de inicio de sesión y vuelve a enviarlo, se registrará una segunda sesión; un cierre de sesión por dispositivo y usuario cerrará ambas.

Notificar un cierre de sesión

Envíe loginId, o un campo de dispositivo y un campo de usuario para cerrar todas las sesiones abiertas que la API haya abierto para ese usuario en ese dispositivo, incluidas las de inscripciones anteriores del mismo hardware.

La respuesta es 200 con la lista de sesiones afectadas. Cerrar una sesión que ya está cerrada no cambia nada y la devuelve tal como está, por lo que el cierre de sesión se puede reintentar de forma segura. Un cierre de sesión por dispositivo y usuario devuelve una lista vacía cuando el usuario no tiene ninguna sesión de API abierta allí.

Campos de sesión

Cada endpoint devuelve sesiones con estos campos. Si un campo no tiene valor, se omite; open siempre está presente. Las horas son instantes ISO-8601 en UTC.

Ejemplos

Notificar un inicio de sesión por número de serie para un usuario de su propio sistema.

curl -X POST "https://api.nomid.tech/emm/api/v1/device-user-logins" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serialNumber": "R58N123ABCD", "externalUserId": "emp-1042", "userName": "Ana Souza"}'

HTTP/1.1 201 Created

{
  "loginId": "5f0c2a8e-3b1d-4e7a-9c64-2d8f1b7e0a93",
  "deviceUser": {
    "id": "b2e47c19-8a3f-4d65-a0e1-6c9d2f5b8e74",
    "name": "Ana Souza",
    "auth": "EXTERNAL",
    "externalUserId": "emp-1042"
  },
  "asset": {
    "assetId": "k3x9m2pa",
    "serialNumber": "R58N123ABCD",
    "name": "Warehouse scanner 12"
  },
  "loginAt": "2026-10-29T11:02:41.518204Z",
  "open": true,
  "loginSource": "API"
}

Cerrar esa sesión con su loginId.

curl -X POST "https://api.nomid.tech/emm/api/v1/device-user-logins/logout" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"loginId": "5f0c2a8e-3b1d-4e7a-9c64-2d8f1b7e0a93"}'

HTTP/1.1 200 OK

[
  {
    "loginId": "5f0c2a8e-3b1d-4e7a-9c64-2d8f1b7e0a93",
    "deviceUser": {
      "id": "b2e47c19-8a3f-4d65-a0e1-6c9d2f5b8e74",
      "name": "Ana Souza",
      "auth": "EXTERNAL",
      "externalUserId": "emp-1042"
    },
    "asset": {
      "assetId": "k3x9m2pa",
      "serialNumber": "R58N123ABCD",
      "name": "Warehouse scanner 12"
    },
    "loginAt": "2026-10-29T11:02:41.518204Z",
    "logoutAt": "2026-10-29T19:30:05.204117Z",
    "open": false,
    "loginSource": "API",
    "logoutSource": "API"
  }
]

O cerrar todas las sesiones de API abiertas del usuario en ese dispositivo.

curl -X POST "https://api.nomid.tech/emm/api/v1/device-user-logins/logout" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serialNumber": "R58N123ABCD", "externalUserId": "emp-1042"}'

Consultar las sesiones de un dispositivo desde el 1 de octubre. Esta es un inicio de sesión mediante PIN en el dispositivo que expiró.

curl "https://api.nomid.tech/emm/api/v1/device-user-logins?serialNumber=R58N123ABCD&from=2026-10-01T00:00:00Z&limit=20" \
  -H "X-API-Key: $NOMID_API_KEY"

HTTP/1.1 200 OK

[
  {
    "loginId": "e91d4b7a-0c2f-4a58-8b13-7f6e5d4c3b2a",
    "deviceUser": {
      "id": "4c8a1e2f-6b3d-4f70-9e15-0a2b3c4d5e6f",
      "name": "Shift 2 operator",
      "auth": "PIN"
    },
    "asset": {
      "assetId": "k3x9m2pa",
      "serialNumber": "R58N123ABCD",
      "name": "Warehouse scanner 12"
    },
    "loginAt": "2026-10-28T14:00:09.731552Z",
    "logoutAt": "2026-10-28T22:00:09.731552Z",
    "expiresAt": "2026-10-28T22:00:09.731552Z",
    "open": false,
    "loginSource": "DEVICE",
    "logoutSource": "EXPIRY"
  }
]

Error: una sesión notificada por el dispositivo

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "The login was reported by the device, not through the API",
  "instance": "/emm/api/v1/device-user-logins/logout",
  "code": "login_not_reported_by_api"
}

Errores

Los endpoints de sesión de Device User responden 400, 404 y 409 con application/problem+json y un miembro code para bifurcar; no envían ningún miembro retryable. Dos excepciones no tienen code: 401 y 403, y un 400 por un parámetro de consulta no válido de GET /device-user-logins.

Límites de frecuencia

Estos puntos de conexión no forman parte del límite de escritura de 10 solicitudes por minuto por clave que comparten los comandos de dispositivo, los cambios de política y los códigos QR de aprovisionamiento. De todos modos, diseñe su cliente para que aplique un tiempo de espera ante un 429.

Herramienta MCP

La herramienta MCP de solo lectura list_device_user_logins admite los mismos filtros como argumentos y necesita DEVICES_READ. Con Sign in with Nomid, un usuario que solo ve algunas políticas únicamente obtiene las sesiones en activos de esas políticas. La notificación de inicios y cierres de sesión solo se realiza mediante REST: ninguna herramienta MCP lo hace.

Servidor MCP