Sessões de Device User

Como funciona

Use estes endpoints quando um aplicativo seu autenticar seus próprios usuários em um dispositivo gerenciado. O aplicativo identifica o dispositivo pelo número de série, por exemplo, um passado a ele em sua configuração gerenciada. Quando um usuário faz login, seu back-end relata o login com esse número de série e seu próprio id para o usuário, e armazena o loginId retornado. Quando o usuário faz logout, seu back-end relata o logout.

O primeiro login de um externalUserId cria um Device User com autenticação EXTERNAL para ele. Logins posteriores do mesmo externalUserId reutilizam esse usuário, e um userName diferente do nome atual o renomeia. Você também pode relatar o login de um Device User existente de qualquer tipo de autenticação pelo seu deviceUserId.

GET /device-user-logins retorna as sessões de Device User da empresa, da mais recente para a mais antiga: aquelas que o seu sistema relata e os logins por PIN e SSO que o agente Nomid relata a partir do dispositivo. loginSource e logoutSource indicam quem relatou cada parte de uma sessão.

Uma sessão relatada por meio da API não expira no Nomid: ela permanece aberta até que você relate o respectivo logout. Cada chamada de login registra uma nova sessão, mesmo quando o mesmo usuário já estiver conectado nesse dispositivo.

A API encerra apenas sessões que foram relatadas por meio da API. Um login por PIN ou SSO no agente Nomid é encerrado pelo dispositivo.

Requisitos

• GET /device-user-logins requer DEVICES_READ, assim como as outras leituras de dispositivos.
• Relatar logins e logouts de Device User (POST /device-user-logins e POST /device-user-logins/logout) requer DEVICES_COMMAND, a permissão que envia comandos para dispositivos; uma chave só a obtém em conjunto com DEVICES_READ. As sessões de Device User não têm uma permissão própria.
• Para relatar um login, o ativo precisa ter um dispositivo gerenciado, ou seja, um dispositivo registrado no Nomid no momento.
• A chave validada seleciona a empresa; as requisições não possuem parâmetros de tenant ou de empresa. Os endpoints de login e logout podem acessar todos os ativos da empresa.

Endpoints

Os caminhos são relativos à URL base da API e exigem o cabeçalho X-API-Key.

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

Listar sessões

Todos os parâmetros de consulta são opcionais. Sem filtros, o endpoint retorna as sessões mais recentes da empresa.

As sessões de um ativo incluem aquelas gravadas em registros anteriores do mesmo hardware, com o mesmo número de série, para que um dispositivo registrado novamente mantenha seu histórico. Um ativo desconhecido retorna 404 com o código asset_not_found; um deviceUserId ou externalUserId desconhecido não corresponde a nenhuma sessão e retorna uma lista vazia.

Informar um login

Envie um campo de dispositivo e um campo de usuário. Enviar ambos ou nenhum de um par retorna 400.

Guarde o loginId da resposta: ele é o comprovante que encerra exatamente esta sessão. Se uma resposta de login for perdida e você enviar o login novamente, uma segunda sessão será registrada; um logout por dispositivo e usuário encerra ambas.

Informar um logout

Envie loginId ou um campo de dispositivo e um campo de usuário para encerrar todas as sessões abertas que a API abriu para aquele usuário naquele dispositivo, inclusive em registros anteriores do mesmo hardware.

A resposta é 200 com a lista de sessões em questão. Encerrar uma sessão que já está fechada não altera nada e a retorna como está; portanto, o logout pode ser repetido com segurança. Um logout por dispositivo e usuário retorna uma lista vazia quando o usuário não tiver nenhuma sessão de API aberta nele.

Campos da sessão

Todos os endpoints retornam sessões com estes campos. Um campo sem valor é omitido; open está sempre presente. Os horários são instantes ISO-8601 em UTC.

Exemplos

Relate um login por número de série para um usuário do seu próprio 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"
}

Encerre essa sessão com seu 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"
  }
]

Ou feche todas as sessões de API abertas do usuário nesse 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"}'

Leia as sessões de um dispositivo desde 1º de outubro. Esta é um login por PIN no dispositivo que expirou.

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"
  }
]

Erro: uma sessão relatada pelo 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"
}

Erros

Os endpoints de sessão do Device User respondem a 400, 404 e 409 com application/problem+json e um membro code para ramificação; eles não enviam um membro retryable. Duas exceções não têm code: 401 e 403, e um 400 para um parâmetro de consulta inválido de GET /device-user-logins.

Limites de taxa

Esses endpoints não fazem parte do limite de gravação de 10 solicitações por minuto por chave compartilhado por comandos de dispositivo, alterações de política e códigos QR de provisionamento. De qualquer forma, programe seu cliente para recuar em caso de 429.

Ferramenta MCP

A ferramenta MCP somente leitura list_device_user_logins aceita os mesmos filtros como argumentos e precisa de DEVICES_READ. Com o Sign in with Nomid, um usuário que vê apenas algumas políticas obtém apenas as sessões em ativos dessas políticas. Informar logins e logouts é somente REST: nenhuma ferramenta MCP faz isso.

Servidor MCP