Device-user sessions

How it works

Use these endpoints when an app of yours authenticates its own users on a managed device. The app identifies the device by its serial number, for example one passed to it in its managed configuration. When a user signs in, your backend reports the login with that serial number and your own id for the user, and keeps the loginId it gets back. When the user signs out, your backend reports the logout.

The first login of an externalUserId creates a device user with auth EXTERNAL for it. Later logins of the same externalUserId reuse that user, and a userName that differs from its current name renames it. You can also report the login of an existing device user of any auth by its deviceUserId.

GET /device-user-logins returns the company's device-user sessions, newest first: those your system reports and the PIN and SSO logins the Nomid agent reports from the device. loginSource and logoutSource say who reported each half of a session.

A session reported through the API has no expiry in Nomid: it stays open until you report its logout. Each login call records a new session, even when the same user is already logged in on that device.

The API closes only sessions that were reported through the API. A PIN or SSO login on the Nomid agent is closed by the device.

Requirements

• GET /device-user-logins needs DEVICES_READ, like the other device reads.
• Reporting device-user logins and logouts (POST /device-user-logins and POST /device-user-logins/logout) needs DEVICES_COMMAND, the permission that sends device commands; a key only gets it together with DEVICES_READ. Device-user sessions have no permission of their own.
• To report a login, the asset must have a managed device, that is, a device enrolled in Nomid now.
• The validated key selects the company; requests have no tenant or company parameter. The login and logout endpoints can address every asset of the company.

Endpoints

Paths are relative to the API base URL and need the X-API-Key header.

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

List sessions

Every query parameter is optional. Without filters, the endpoint returns the company's latest sessions.

An asset's sessions include those recorded on earlier enrollments of the same hardware, with the same serial number, so a re-enrolled device keeps its history. An unknown asset returns 404 with code asset_not_found; an unknown deviceUserId or externalUserId matches no session and returns an empty list.

Report a login

Send one device field and one user field. Sending both or neither of a pair returns 400.

Keep the loginId from the response: it is the receipt that logs out exactly this session. If a login response is lost and you send the login again, a second session is recorded; a logout by device and user closes both.

Report a logout

Send either loginId, or a device field and a user field to close every open session the API opened for that user on that device, including on earlier enrollments of the same hardware.

The response is 200 with the list of sessions concerned. Logging out a session that is already closed changes nothing and returns it as it is, so a logout can be retried safely. A logout by device and user returns an empty list when the user has no open API session there.

Session fields

Every endpoint returns sessions with these fields. A field without a value is omitted; open is always present. Times are ISO-8601 instants in UTC.

Examples

Report a login by serial number for a user of your own system.

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

Log that session out with its 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"
  }
]

Or close every open API session of the user on that device.

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

Read the sessions of one device since October 1. This one is a PIN login on the device that expired.

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: a session the device reported

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

Errors

The device-user session endpoints answer 400, 404 and 409 with application/problem+json and a code member to branch on; they send no retryable member. Two exceptions have no code: 401 and 403, and a 400 for an invalid query parameter of GET /device-user-logins.

Rate limits

These endpoints are not part of the write limit of 10 requests per minute per key that device commands, policy changes and provisioning QR codes share. Build your client to back off on 429 anyway.

MCP tool

The read-only MCP tool list_device_user_logins takes the same filters as arguments and needs DEVICES_READ. With Sign in with Nomid, a user who sees only some policies gets only the sessions on assets of those policies. Reporting logins and logouts is REST only: no MCP tool does it.

MCP server