Sessões de Device User

Como funciona

Utilize estes endpoints quando uma aplicação sua autentica os seus próprios utilizadores num dispositivo gerido. A aplicação identifica o dispositivo através do seu número de série, por exemplo, um transmitido na respetiva configuração gerida. Quando um utilizador inicia sessão, o seu backend comunica o início de sessão com esse número de série e o seu próprio id para o utilizador, mantendo o loginId devolvido. Quando o utilizador termina sessão, o seu backend comunica o término de sessão.

O primeiro início de sessão de um externalUserId cria um Device User com a autenticação EXTERNAL para o mesmo. Inícios de sessão posteriores do mesmo externalUserId reutilizam esse utilizador, e um userName que difira do seu nome atual renomeia-o. Também pode comunicar o início de sessão de um Device User existente de qualquer autenticação através do seu deviceUserId.

GET /device-user-logins devolve as sessões de Device User da empresa, as mais recentes primeiro: as que o seu sistema comunica e os inícios de sessão por PIN e SSO que o agente Nomid comunica a partir do dispositivo. loginSource e logoutSource indicam quem comunicou cada metade de uma sessão.

Uma sessão comunicada através da API não tem expiração no Nomid: permanece aberta até que comunique o respetivo término de sessão. Cada chamada de início de sessão regista uma nova sessão, mesmo quando o mesmo utilizador já tem sessão iniciada nesse dispositivo.

A API encerra apenas sessões que tenham sido comunicadas através da API. Um início de sessão por PIN ou SSO no agente Nomid é encerrado pelo dispositivo.

Requisitos

• GET /device-user-logins requer DEVICES_READ, tal como as outras leituras de dispositivos.
• A comunicação de inícios e términos de sessão 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 comunicar um início de sessão, o ativo tem de ter um dispositivo gerido, ou seja, um dispositivo atualmente inscrito no Nomid.
• A chave validada seleciona a empresa; os pedidos não têm nenhum parâmetro de tenant ou de empresa. Os endpoints de início e término de sessão podem endereçar todos os ativos da empresa.

Endpoints

Os caminhos são relativos ao URL base da API e requerem 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 devolve as sessões mais recentes da empresa.

As sessões de um ativo incluem as gravadas em inscrições anteriores do mesmo hardware, com o mesmo número de série, pelo que um dispositivo reinscrito mantém o seu histórico. Um ativo desconhecido devolve 404 com o código asset_not_found; um deviceUserId ou externalUserId desconhecido não corresponde a nenhuma sessão e devolve uma lista vazia.

Comunicar um início de sessão

Envie um campo de dispositivo e um campo de utilizador. O envio de ambos ou de nenhum devolve 400.

Guarde o loginId da resposta: é o comprovativo que termina exatamente esta sessão. Se uma resposta de início de sessão se perder e enviar o início de sessão novamente, é gravada uma segunda sessão; um fim de sessão por dispositivo e utilizador fecha ambas.

Comunicar um fim de sessão

Envie loginId ou um campo de dispositivo e um campo de utilizador para fechar todas as sessões abertas que a API abriu para esse utilizador nesse dispositivo, incluindo em inscrições anteriores do mesmo hardware.

A resposta é 200 com a lista das sessões em questão. Terminar uma sessão que já está fechada não altera nada e devolve-a tal como está, pelo que um encerramento de sessão pode ser repetido em segurança. Um encerramento de sessão por dispositivo e utilizador devolve uma lista vazia quando o utilizador não tem nenhuma sessão de API aberta no mesmo.

Campos da sessão

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

Exemplos

Comunicar um início de sessão por número de série para um utilizador 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"
}

Terminar essa sessão com o respetivo 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 fechar todas as sessões de API abertas do utilizador 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"}'

Ler as sessões de um dispositivo desde 1 de outubro. Esta é um início de sessão 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 comunicada 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 de Device User respondem com 400, 404 e 409 com application/problem+json e um membro code para ramificação; não enviam nenhum 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 pedidos

Estes endpoints não fazem parte do limite de escrita de 10 pedidos por minuto por chave que os comandos de dispositivo, as alterações de políticas e os códigos QR de aprovisionamento partilham. Ainda assim, desenvolva o seu cliente de forma a abrandar em caso de 429.

Ferramenta MCP

A ferramenta MCP apenas de leitura list_device_user_logins aceita os mesmos filtros como argumentos e necessita de DEVICES_READ. Com o Sign in with Nomid, um utilizador que vê apenas algumas políticas obtém apenas as sessões em ativos dessas políticas. A comunicação de inícios e fins de sessão é apenas por REST: nenhuma ferramenta MCP o faz.

Servidor MCP