Commandes d'appareils

Vue d'ensemble

Chaque appel agit sur un seul appareil, identifié par son assetId, qui correspond au pathName renvoyé par GET /assets. Il n'existe aucun point de terminaison de traitement par lots. Pour commander plusieurs appareils, effectuez un appel par appareil dans la limite de débit autorisée. Les points de terminaison effectuent la même action que les outils de commande MCP.

La clé nécessite DEVICES_COMMAND et DEVICES_READ. change-policy nécessite également POLICIES_READ. Les commandes destructives nécessitent plutôt DEVICES_COMMAND_DESTRUCTIVE et DEVICES_READ. Envoyez la clé dans l'en-tête X-API-Key. L'API REST n'accepte pas d'en-tête Authorization.

L'appareil doit être enregistré (statut ACTIVE, INACTIVE ou SYNCHRONIZING). Certaines commandes ne fonctionnent que sur un type d'appareil, comme l'indique chaque description ci-dessous : appareils Android Management (gérés par Google) ou appareils gérés par l'agent Nomid (AOSP). Tout autre appareil reçoit une réponse 409. Un message est une notification push envoyée à l'agent Nomid et nécessite un jeton push enregistré.

Points de terminaison

Envoyez Content-Type: application/json avec les points de terminaison lost-mode, message, launch-app, clear-app-data, change-policy et change-screen-lock-password. Les autres points de terminaison ne prennent aucun corps. Les champs inconnus sont rejetés et les champs de texte obligatoires ne peuvent pas être vides.

Commandes destructives

Quatre commandes effacent les données, suppriment ou remplacent le verrouillage de l'écran, ou mettent fin à la gestion de l'appareil. Avec une clé d'API, elles s'exécutent dès que la requête est acceptée. Il n'y a aucune étape d'approbation dans le portail.

Elles nécessitent une clé d'API avec DEVICES_COMMAND_DESTRUCTIVE et DEVICES_READ. L'entreprise doit également activer les commandes destructives sous l'accès agent IA dans le portail. Ce paramètre est désactivé par défaut et nécessite que les commandes d'appareil soient également activées. Sans cela, la requête renvoie une erreur 403 avec le code forbidden.

change-screen-lock-password prend le nouveau mot de passe dans newPassword. Nomid ne le stocke, ne le renvoie ni ne le consigne jamais dans les journaux.

Corps de requête

Corps de requête du mode perdu

Corps de requête du message

Exemple : envoyer un message

Remplacez l'ID de l'actif par un pathName issu de GET /assets, et conservez la clé dans une variable d'environnement.

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/message" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Please return this device", "body": "Bring it to the IT desk by 5 pm."}'

{
  "assetId": "k3x9m2pa",
  "type": "NOTIFICATION_MESSAGE",
  "status": "SUCCESS",
  "createdAt": "2026-10-06T14:30:00Z"
}

Une réponse 200 signifie que la commande a été créée. Le champ status indique l'état de la commande lors du retour de la requête. Pour un message, SUCCESS signifie que le push a été accepté pour la livraison, et non que l'utilisateur l'a vu. Poursuivez avec GET /assets/ASSET_ID/commands.

Exemple : verrouiller un appareil

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/lock" \
  -H "X-API-Key: $NOMID_API_KEY"

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "IN_PROGRESS",
  "createdAt": "2026-10-06T14:30:00Z"
}

Le verrouillage et le mode perdu renvoient IN_PROGRESS tant que l'appareil n'a pas encore confirmé la commande. L'historique des commandes affiche SUCCESS une fois que c'est fait. Le point de terminaison lock ne prend aucun corps.

Exemple : effacer un appareil

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/wipe" \
  -H "X-API-Key: $NOMID_API_KEY"

{
  "assetId": "k3x9m2pa",
  "type": "WIPE_COMPANY_DATA",
  "status": "IN_PROGRESS"
}

Un effacement d'un appareil Android Management répond IN_PROGRESS sans createdAt. Consultez l'historique des commandes pour le suivre.

Réponses et mesures à prendre

Les règles de nouvelle tentative sont importantes. Réessayer une commande dont l'issue est inconnue peut entraîner son exécution en double.

Corps d'erreur

Les erreurs provenant des points de terminaison de commande utilisent application/problem+json (RFC 9457). Sur les points de terminaison lock, lost-mode, found et message, les erreurs 401 et 429 renvoient un petit objet JSON avec error, message et status, 404 n'a pas de corps, et seuls 502 et 503 ajoutent un champ booléen retryable. Sur les autres points de terminaison, chaque erreur hormis 401 correspond aux détails du problème avec un champ code, tel que not_found, unsupported, forbidden, invalid_arguments ou rate_limited, et 429, 500, 502 et 503 comportent également retryable. Une réponse 202 n'est pas une erreur : elle contient l'objet de résultat normal.

Exemple de réponse 202

HTTP/1.1 202 Accepted

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "UNCONFIRMED",
  "detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
}

Exemple de réponse 503

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Command was not sent; it is safe to retry.",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "retryable": true
}

Exemple de réponse 404 provenant d'un point de terminaison autre que lock, lost-mode, found et message

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No device found with assetId: k3x9m2pa",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/reboot",
  "code": "not_found"
}

Limite de fréquence

Les commandes sont limitées à 10 par minute et par clé d'API, commandes destructives incluses. Le même quota est partagé avec les outils de commande MCP, les modifications de stratégie (chaque appel propose et apply) et les codes QR d'enrôlement, via REST ou MCP. Via REST, les requêtes dépassant la limite reçoivent une erreur HTTP 429 avec un en-tête Retry-After.

Sur les points de terminaison lock, lost-mode, found et message, seules les clés disposant de DEVICES_COMMAND consomment ce quota, et une requête avec un corps non valide ou un identifiant d'actif inconnu est tout de même comptabilisée, car la limite est appliquée avant la validation de la requête. Les autres points de terminaison de commande, les appels de modification de stratégie et les requêtes de code QR d'enrôlement ne le consomment qu'une fois que la requête a passé avec succès les vérifications d'autorisations et la validation des arguments.

Piste d'audit

Chaque commande est enregistrée dans l'historique des commandes de l'appareil au sein du portail Nomid et attribuée à la clé d'API qui l'a envoyée, et non à une personne. L'entrée indique api-key, l'identifiant de la clé et le préfixe de la clé. L'historique renvoyé par GET /assets/ASSET_ID/commands et par l'outil MCP list_device_commands contient uniquement type, status, createdAt, feedbackAt et outcome, mais pas l'auteur de l'envoi de la commande.

• Référence de l'API Assets
• Gestion des erreurs
• Guide du serveur MCP