Device-User-Sitzungen

Funktionsweise

Verwenden Sie diese Endpunkte, wenn eine Ihrer Apps ihre eigenen Benutzer auf einem verwalteten Gerät authentifiziert. Die App identifiziert das Gerät anhand seiner Seriennummer, beispielsweise über eine Nummer, die ihr in ihrer verwalteten Konfiguration übergeben wurde. Wenn sich ein Benutzer anmeldet, meldet Ihr Backend die Anmeldung mit dieser Seriennummer und Ihrer eigenen ID für den Benutzer und speichert die zurückgegebene loginId. Wenn sich der Benutzer abmeldet, meldet Ihr Backend die Abmeldung.

Die erste Anmeldung einer externalUserId erstellt dafür einen Device-User mit auth EXTERNAL. Spätere Anmeldungen derselben externalUserId verwenden diesen Benutzer wieder, und ein userName, der vom aktuellen Namen abweicht, benennt ihn um. Sie können auch die Anmeldung eines bestehenden Device-Users mit beliebiger Authentifizierung über dessen deviceUserId melden.

GET /device-user-logins gibt die Device-User-Sitzungen des Unternehmens zurück, die neuesten zuerst: diejenigen, die Ihr System meldet, sowie die PIN- und SSO-Anmeldungen, die der Nomid-Agent vom Gerät meldet. loginSource und logoutSource geben an, wer die jeweilige Hälfte einer Sitzung gemeldet hat.

Eine über die API gemeldete Sitzung läuft in Nomid nicht ab: Sie bleibt geöffnet, bis Sie deren Abmeldung melden. Jeder Anmeldeaufruf zeichnet eine neue Sitzung auf, selbst wenn derselbe Benutzer bereits auf diesem Gerät angemeldet ist.

Die API schließt nur Sitzungen, die über die API gemeldet wurden. Eine PIN- oder SSO-Anmeldung im Nomid-Agenten wird durch das Gerät geschlossen.

Voraussetzungen

• GET /device-user-logins erfordert DEVICES_READ, genau wie die anderen Lesezugriffe für Geräte.
• Das Melden von An- und Abmeldungen von Device-Usern (POST /device-user-logins und POST /device-user-logins/logout) erfordert DEVICES_COMMAND, die Berechtigung, die Gerätebefehle sendet; ein Schlüssel erhält diese nur zusammen mit DEVICES_READ. Device-User-Sitzungen verfügen über keine eigene Berechtigung.
• Um eine Anmeldung zu melden, muss das Asset über ein verwaltetes Gerät verfügen, das heißt über ein Gerät, das aktuell in Nomid registriert ist.
• Der validierte Schlüssel wählt das Unternehmen aus; Anfragen haben keinen Tenant- oder Unternehmensparameter. Die An- und Abmelde-Endpunkte können jedes Asset des Unternehmens adressieren.

Endpunkte

Pfade sind relativ zur Basis-URL der API und erfordern den Header X-API-Key.

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

Sitzungen auflisten

Jeder Abfrageparameter ist optional. Ohne Filter gibt der Endpunkt die neuesten Sitzungen des Unternehmens zurück.

Die Sitzungen eines Assets umfassen auch diejenigen, die bei früheren Registrierungen derselben Hardware mit derselben Seriennummer erfasst wurden, sodass ein erneut registriertes Gerät seinen Verlauf behält. Ein unbekanntes Asset gibt 404 mit dem Code asset_not_found zurück; eine unbekannte deviceUserId oder externalUserId stimmt mit keiner Sitzung überein und gibt eine leere Liste zurück.

Anmeldung melden

Senden Sie ein Gerätefeld und ein Benutzerfeld. Das Senden von beiden oder keinem eines Paars gibt 400 zurück.

Bewahren Sie die loginId aus der Antwort auf: Sie ist der Beleg, mit dem genau diese Sitzung abgemeldet wird. Geht eine Anmeldeantwort verloren und Sie senden die Anmeldung erneut, wird eine zweite Sitzung erfasst; eine Abmeldung nach Gerät und Benutzer schließt beide.

Abmeldung melden

Senden Sie entweder loginId oder ein Gerätefeld und ein Benutzerfeld, um jede offene Sitzung zu schließen, die die API für diesen Benutzer auf diesem Gerät geöffnet hat, einschließlich bei früheren Registrierungen derselben Hardware.

Die Antwort ist 200 mit der Liste der betroffenen Sitzungen. Das Abmelden einer bereits geschlossenen Sitzung ändert nichts und gibt sie unverändert zurück, sodass eine Abmeldung sicher wiederholt werden kann. Eine Abmeldung nach Gerät und Benutzer gibt eine leere Liste zurück, wenn der Benutzer dort keine offene API-Sitzung hat.

Sitzungsfelder

Jeder Endpunkt gibt Sitzungen mit diesen Feldern zurück. Ein Feld ohne Wert wird weggelassen; open ist immer vorhanden. Zeitangaben sind ISO-8601-Zeitpunkte in UTC.

Beispiele

Eine Anmeldung anhand der Seriennummer für einen Benutzer Ihres eigenen Systems melden.

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

Diese Sitzung mit ihrer loginId abmelden.

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

Oder jede offene API-Sitzung des Benutzers auf diesem Gerät schließen.

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

Die Sitzungen eines Geräts seit dem 1. Oktober abrufen. Dies ist eine abgelaufene PIN-Anmeldung auf dem Gerät.

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

Fehler: Eine vom Gerät gemeldete Sitzung

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

Fehler

Die Endpunkte für Device-User-Sitzungen antworten bei 400, 404 und 409 mit application/problem+json und einem code-Member zur Verzweigung; sie senden kein retryable-Member. Zwei Ausnahmen haben keinen code: 401 und 403 sowie ein 400 für einen ungültigen Abfrageparameter von GET /device-user-logins.

Ratenbegrenzungen

Diese Endpunkte unterliegen nicht dem Schreiblimit von 10 Anfragen pro Minute und Schlüssel, das sich Gerätebefehle, Richtlinienänderungen und Bereitstellungs-QR-Codes teilen. Implementieren Sie Ihren Client dennoch so, dass er bei einem 429-Fehler eine Wartezeit einlegt (Backoff).

MCP-Tool

Das schreibgeschützte MCP-Tool list_device_user_logins akzeptiert dieselben Filter als Argumente und erfordert DEVICES_READ. Bei „Sign in with Nomid“ erhält ein Benutzer, der nur bestimmte Richtlinien sehen darf, nur die Sitzungen auf Assets dieser Richtlinien. Das Melden von An- und Abmeldungen ist ausschließlich per REST möglich: Kein MCP-Tool führt dies aus.

MCP-Server