Sessions d'utilisateurs d'appareils

Fonctionnement

Utilisez ces points de terminaison lorsqu'une de vos applications authentifie ses propres utilisateurs sur un appareil géré. L'application identifie l'appareil par son numéro de série, par exemple celui qui lui est transmis dans sa configuration gérée. Lorsqu'un utilisateur se connecte, votre backend signale la connexion avec ce numéro de série et votre propre identifiant d'utilisateur, puis conserve le loginId renvoyé. Lorsque l'utilisateur se déconnecte, votre backend signale la déconnexion.

La première connexion d'un externalUserId crée un utilisateur d'appareil associé avec l'authentification EXTERNAL. Les connexions ultérieures du même externalUserId réutilisent cet utilisateur, et un userName différent de son nom actuel le renomme. Vous pouvez également signaler la connexion d'un utilisateur d'appareil existant, quel que soit son type d'authentification, à l'aide de son deviceUserId.

GET /device-user-logins renvoie les sessions d'utilisateurs d'appareils de l'entreprise, de la plus récente à la plus ancienne : celles signalées par votre système et les connexions par code PIN et SSO signalées par l'agent Nomid depuis l'appareil. loginSource et logoutSource indiquent qui a signalé chaque moitié d'une session.

Une session signalée via l'API n'a pas d'expiration dans Nomid : elle reste ouverte jusqu'à ce que vous signaliez sa déconnexion. Chaque appel de connexion enregistre une nouvelle session, même lorsque le même utilisateur est déjà connecté sur cet appareil.

L'API ne ferme que les sessions qui ont été signalées via l'API. Une connexion par code PIN ou SSO sur l'agent Nomid est fermée par l'appareil.

Prérequis

• GET /device-user-logins nécessite DEVICES_READ, comme les autres lectures d'appareils.
• Le signalement des connexions et déconnexions d'utilisateurs d'appareils (POST /device-user-logins et POST /device-user-logins/logout) nécessite DEVICES_COMMAND, l'autorisation qui envoie des commandes aux appareils ; une clé ne l'obtient qu'avec DEVICES_READ. Les sessions d'utilisateurs d'appareils n'ont pas d'autorisation propre.
• Pour signaler une connexion, l'actif doit avoir un appareil géré, c'est-à-dire un appareil actuellement inscrit dans Nomid.
• La clé validée sélectionne l'entreprise ; les requêtes ne comportent aucun paramètre de tenant ou d'entreprise. Les points de terminaison de connexion et de déconnexion peuvent s'adresser à tous les actifs de l'entreprise.

Points de terminaison

Les chemins sont relatifs à l'URL de base de l'API et nécessitent l'en-tête X-API-Key.

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

Lister les sessions

Chaque paramètre de requête est facultatif. Sans filtres, le point de terminaison renvoie les dernières sessions de l'entreprise.

Les sessions d'un actif incluent celles consignées lors d'inscriptions antérieures du même matériel, avec le même numéro de série, de sorte qu'un appareil réinscrit conserve son historique. Un actif inconnu renvoie 404 avec le code asset_not_found ; un deviceUserId ou externalUserId inconnu ne correspond à aucune session et renvoie une liste vide.

Signaler une connexion

Transmettez un champ d'appareil et un champ d'utilisateur. Envoyer les deux ou aucun champ d'une paire renvoie 400.

Conservez le loginId de la réponse : c'est le reçu qui permet de déconnecter précisément cette session. Si une réponse de connexion est perdue et que vous envoyez à nouveau la connexion, une deuxième session est créée ; une déconnexion par appareil et utilisateur ferme les deux.

Signaler une déconnexion

Transmettez soit loginId, soit un champ d'appareil et un champ d'utilisateur pour fermer toutes les sessions ouvertes créées par l'API pour cet utilisateur sur cet appareil, y compris lors d'inscriptions antérieures du même matériel.

La réponse est 200 avec la liste des sessions concernées. Déconnecter une session déjà fermée ne change rien et la renvoie telle quelle, une déconnexion peut donc être réessayée en toute sécurité. Une déconnexion par appareil et utilisateur renvoie une liste vide lorsque l'utilisateur n'y a aucune session API ouverte.

Champs de session

Chaque point de terminaison renvoie des sessions avec ces champs. Un champ sans valeur est omis ; open est toujours présent. Les heures sont des instants ISO-8601 en UTC.

Exemples

Signaler une connexion par numéro de série pour un utilisateur de votre propre système.

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

Déconnecter cette session avec son 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 fermer chaque session API ouverte de l'utilisateur sur cet appareil.

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

Consulter les sessions d'un appareil depuis le 1er octobre. Celle-ci est une connexion PIN sur l'appareil qui a expiré.

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

Erreur : une session signalée par l'appareil

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

Erreurs

Les points de terminaison de session Device User répondent 400, 404 et 409 avec application/problem+json et un membre code pour le branchement conditionnel ; ils n'envoient aucun membre retryable. Deux exceptions n'ont pas de code : 401 et 403, ainsi qu'une réponse 400 en cas de paramètre de requête non valide pour GET /device-user-logins.

Limites de débit

Ces points de terminaison ne font pas partie de la limite d'écriture de 10 requêtes par minute et par clé que partagent les commandes d'appareils, les modifications de stratégie et les codes QR de provisionnement. Concevez tout de même votre client pour qu'il temporise en cas d'erreur 429.

Outil MCP

L'outil MCP en lecture seule list_device_user_logins prend les mêmes filtres comme arguments et nécessite DEVICES_READ. Avec Sign in with Nomid, un utilisateur qui ne voit que certaines stratégies n'obtient que les sessions sur les actifs associés à ces stratégies. Le signalement des connexions et déconnexions s'effectue uniquement via REST : aucun outil MCP ne le permet.

Serveur MCP