Sesje użytkowników urządzeń

Jak to działa

Używaj tych punktów końcowych, gdy Twoja aplikacja uwierzytelnia własnych użytkowników na zarządzanym urządzeniu. Aplikacja identyfikuje urządzenie po jego numerze seryjnym, na przykład przekazanym w konfiguracji zarządzanej. Gdy użytkownik się loguje, Twój backend zgłasza logowanie z tym numerem seryjnym oraz Twoim własnym identyfikatorem użytkownika, a następnie zachowuje zwrócony loginId. Gdy użytkownik się wylogowuje, Twój backend zgłasza wylogowanie.

Pierwsze logowanie danego externalUserId tworzy dla niego użytkownika urządzenia z metodą uwierzytelniania EXTERNAL. Kolejne logowania z tym samym externalUserId ponownie wykorzystują tego użytkownika, a nazwa userName różniąca się od jego bieżącej nazwy zmienia ją. Możesz również zgłosić logowanie istniejącego użytkownika urządzenia o dowolnym typie uwierzytelniania, używając jego deviceUserId.

GET /device-user-logins zwraca sesje użytkowników urządzeń w firmie, od najnowszych: te zgłoszone przez Twój system oraz logowania PIN i SSO zgłaszane z urządzenia przez agenta Nomid. loginSource i logoutSource wskazują, kto zgłosił daną część sesji.

Sesja zgłoszona przez API nie wygasa w Nomid: pozostaje otwarta do momentu zgłoszenia jej wylogowania. Każde wywołanie logowania rejestruje nową sesję, nawet jeśli ten sam użytkownik jest już zalogowany na tym urządzeniu.

API zamyka tylko te sesje, które zostały zgłoszone przez API. Logowanie za pomocą kodu PIN lub SSO w agencie Nomid jest zamykane przez urządzenie.

Wymagania

• GET /device-user-logins wymaga uprawnienia DEVICES_READ, podobnie jak inne operacje odczytu urządzeń.
• Zgłaszanie logowań i wylogowań użytkowników urządzeń (POST /device-user-logins i POST /device-user-logins/logout) wymaga uprawnienia DEVICES_COMMAND, które służy do wysyłania poleceń do urządzeń; klucz może je otrzymać tylko razem z DEVICES_READ. Sesje użytkowników urządzeń nie mają własnego uprawnienia.
• Aby zgłosić logowanie, zasób musi posiadać zarządzane urządzenie, czyli urządzenie aktualnie zarejestrowane w Nomid.
• Zweryfikowany klucz określa firmę; żądania nie zawierają parametru organizacji (tenant) ani firmy. Punkty końcowe logowania i wylogowania mogą odnosić się do każdego zasobu w firmie.

Punkty końcowe

Ścieżki są względne wobec bazowego adresu URL API i wymagają nagłówka X-API-Key.

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

Pobierz listę sesji

Każdy parametr zapytania jest opcjonalny. Bez filtrów punkt końcowy zwraca najnowsze sesje firmy.

Sesje zasobu obejmują te zarejestrowane podczas wcześniejszych rejestracji tego samego sprzętu, o tym samym numerze seryjnym, dzięki czemu ponownie zarejestrowane urządzenie zachowuje swoją historię. Nieznany zasób zwraca błąd 404 z kodem asset_not_found; nieznany identyfikator deviceUserId lub externalUserId nie pasuje do żadnej sesji i zwraca pustą listę.

Zgłoś logowanie

Wyślij jedno pole urządzenia i jedno pole użytkownika. Wysłanie obu lub żadnego z pary zwraca błąd 400.

Zachowaj loginId z odpowiedzi: jest to potwierdzenie, które wylogowuje dokładnie tę sesję. Jeśli odpowiedź na logowanie zostanie utracona i logowanie zostanie wysłane ponownie, zarejestrowana zostanie druga sesja; wylogowanie według urządzenia i użytkownika zamyka obie.

Zgłoś wylogowanie

Wyślij loginId albo pole urządzenia i pole użytkownika, aby zamknąć każdą otwartą sesję utworzoną przez API dla tego użytkownika na tym urządzeniu, w tym podczas wcześniejszych rejestracji tego samego sprzętu.

Odpowiedź to 200 z listą powiązanych sesji. Wylogowanie sesji, która jest już zamknięta, niczego nie zmienia i zwraca ją w obecnym stanie, dzięki czemu wylogowanie można bezpiecznie ponowić. Wylogowanie według urządzenia i użytkownika zwraca pustą listę, gdy użytkownik nie ma tam żadnej otwartej sesji API.

Pola sesji

Każdy punkt końcowy zwraca sesje zawierające te pola. Pole bez wartości jest pomijane; pole open występuje zawsze. Czasy podawane są w formacie ISO-8601 w strefie UTC.

Przykłady

Zgłoś logowanie według numeru seryjnego dla użytkownika z Twojego systemu.

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

Wyloguj tę sesję przy użyciu jej parametru 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"
  }
]

Lub zamknij każdą otwartą sesję API użytkownika na tym urządzeniu.

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

Odczytaj sesje jednego urządzenia od 1 października. Ta sesja to logowanie kodem PIN na urządzeniu, które wygasło.

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

Błąd: sesja zgłoszona przez urządzenie

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

Błędy

Punkty końcowe sesji użytkownika urządzenia zwracają błędy 400, 404 i 409 w formacie application/problem+json z polem code służącym do obsługi warunkowej; nie przesyłają pola retryable. Dwa wyjątki nie posiadają kodu: 401 i 403, a także błąd 400 dla nieprawidłowego parametru zapytania w GET /device-user-logins.

Limity żądań

Te punkty końcowe nie są objęte limitem zapisu wynoszącym 10 żądań na minutę na klucz, współdzielonym przez polecenia urządzeń, zmiany zasad i kody QR do aprowizacji. Mimo to zaprogramuj klienta tak, aby ponawiał próby z opóźnieniem w przypadku błędu 429.

Narzędzie MCP

Narzędzie MCP list_device_user_logins tylko do odczytu przyjmuje te same filtry jako argumenty i wymaga uprawnienia DEVICES_READ. W przypadku korzystania z Sign in with Nomid użytkownik, który widzi tylko niektóre zasady, otrzymuje wyłącznie sesje na zasobach objętych tymi zasadami. Zgłaszanie logowań i wylogowań jest dostępne wyłącznie przez interfejs REST: żadne narzędzie MCP tego nie wykonuje.

Serwer MCP