Gerätebefehle

Übersicht

Jeder Aufruf wirkt sich auf genau ein Gerät aus, das durch seine assetId identifiziert wird, bei der es sich um den von GET /assets zurückgegebenen pathName handelt. Es gibt keinen Bulk-Endpunkt. Um mehrere Geräte zu steuern, führen Sie innerhalb des Ratenlimits einen Aufruf pro Gerät aus. Die Endpunkte tun dasselbe wie die MCP-Befehlswerkzeuge.

Der Schlüssel benötigt DEVICES_COMMAND und DEVICES_READ. change-policy benötigt außerdem POLICIES_READ. Die destruktiven Befehle benötigen stattdessen DEVICES_COMMAND_DESTRUCTIVE und DEVICES_READ. Senden Sie den Schlüssel im Header X-API-Key. Die REST-API akzeptiert keinen Authorization-Header.

Das Gerät muss registriert sein (Status ACTIVE, INACTIVE oder SYNCHRONIZING). Einige Befehle funktionieren nur bei einer bestimmten Geräteart, wie in der jeweiligen Beschreibung unten angegeben: Geräte mit Android Management (von Google verwaltet) oder Geräte, die vom Nomid-Agenten (AOSP) verwaltet werden. Jedes andere Gerät erhält 409. Eine Nachricht ist eine Push-Benachrichtigung an den Nomid-Agenten und erfordert ein registriertes Push-Token.

Endpunkte

Senden Sie Content-Type: application/json bei den Endpunkten lost-mode, message, launch-app, clear-app-data, change-policy und change-screen-lock-password. Die anderen Endpunkte erwarten keinen Body. Unbekannte Felder werden abgelehnt, und erforderliche Textfelder dürfen nicht leer sein.

Destruktive Befehle

Vier Befehle löschen Daten, entfernen oder ersetzen die Bildschirmsperre oder beenden die Verwaltung des Geräts. Mit einem API-Schlüssel werden sie ausgeführt, sobald die Anfrage akzeptiert wird. Es gibt keinen Genehmigungsschritt im Portal.

Sie erfordern einen API-Schlüssel mit DEVICES_COMMAND_DESTRUCTIVE und DEVICES_READ. Das Unternehmen muss außerdem destruktive Befehle unter „KI-Agent-Zugriff“ im Portal aktivieren. Diese Einstellung ist standardmäßig deaktiviert und erfordert, dass auch Gerätebefehle aktiviert sind. Ohne dies gibt die Anfrage 403 mit dem Code forbidden zurück.

change-screen-lock-password nimmt das neue Passwort in newPassword entgegen. Nomid speichert, gibt zurück oder protokolliert es zu keinem Zeitpunkt.

Request-Bodys

Request-Body für den Modus für verlorene Geräte

Request-Body für Nachrichten

Beispiel: Eine Nachricht senden

Ersetzen Sie die Asset-ID durch einen pathName aus GET /assets und bewahren Sie den Schlüssel in einer Umgebungsvariable auf.

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

Eine 200-Antwort bedeutet, dass der Befehl erstellt wurde. Das status-Feld gibt den Zustand des Befehls zum Zeitpunkt der Rückgabe der Anfrage an. Bei einer Nachricht bedeutet SUCCESS, dass der Push zur Zustellung angenommen wurde, nicht, dass der Benutzer ihn gesehen hat. Fragen Sie anschließend mit GET /assets/ASSET_ID/commands nach.

Beispiel: Ein Gerät sperren

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

lock und lost-mode geben IN_PROGRESS zurück, solange das Gerät den Befehl noch nicht bestätigt hat. Der Befehlsverlauf zeigt SUCCESS an, sobald dies geschieht. Der Endpunkt lock nimmt keinen Body entgegen.

Beispiel: Ein Gerät löschen

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

Das Löschen eines Android Management-Geräts antwortet mit IN_PROGRESS ohne createdAt. Überprüfen Sie den Befehlsverlauf, um den Vorgang zu verfolgen.

Antworten und was zu tun ist

Die Wiederholungsregeln sind wichtig. Das Wiederholen eines Befehls mit unbekanntem Ausgang kann dazu führen, dass er zweimal zugestellt wird.

Fehler-Bodys

Fehler von den Befehls-Endpunkten verwenden application/problem+json (RFC 9457). Bei den Endpunkten lock, lost-mode, found und message geben 401 und 429 ein kleines JSON-Objekt mit error, message und status zurück, 404 hat keinen Body, und nur 502 und 503 fügen ein boolesches retryable-Feld hinzu. Bei den anderen Endpunkten ist jeder Fehler außer 401 eine Problem-Details-Antwort mit einem code-Feld, wie not_found, unsupported, forbidden, invalid_arguments oder rate_limited, und 429, 500, 502 und 503 enthalten ebenfalls retryable. Eine 202-Antwort ist kein Fehler: Sie enthält das normale Ergebnisobjekt.

Beispiel für eine 202-Antwort

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

Beispiel für eine 503-Antwort

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
}

Beispiel für eine 404-Antwort von einem anderen Endpunkt als lock, lost-mode, found und 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"
}

Ratenlimit

Befehle sind auf 10 pro Minute pro API-Schlüssel begrenzt, einschließlich destruktiver Befehle. Dasselbe Budget wird über REST oder MCP mit den MCP-Befehlswerkzeugen, mit Richtlinienänderungen (jeder Propose- und Apply-Aufruf) und mit Bereitstellungs-QR-Codes geteilt. Über REST erhalten Anfragen, die das Limit überschreiten, HTTP 429 mit einem Retry-After-Header.

Bei den Endpunkten lock, lost-mode, found und message verbrauchen nur Schlüssel mit DEVICES_COMMAND dieses Budget, und eine Anfrage mit einem ungültigen Body oder einer unbekannten Asset-ID zählt trotzdem, da das Limit vor der Validierung der Anfrage angewendet wird. Die anderen Befehls-Endpunkte, Aufrufe zur Richtlinienänderung und Anfragen für Bereitstellungs-QR-Codes verbrauchen es erst, nachdem die Anfrage die Berechtigungsprüfungen und die Argumentvalidierung bestanden hat.

Audit-Trail

Jeder Befehl wird im Befehlsverlauf des Geräts im Nomid-Portal aufgezeichnet und dem API-Schlüssel zugeordnet, der ihn gesendet hat, nicht einer Person. Der Eintrag zeigt api-key, die Schlüssel-ID und das Schlüsselpräfix. Der von GET /assets/ASSET_ID/commands und vom MCP-Werkzeug list_device_commands zurückgegebene Verlauf enthält nur type, status, createdAt, feedbackAt und outcome, nicht jedoch, wer den Befehl gesendet hat.

• Assets-API-Referenz
• Fehlerbehandlung
• MCP-Server-Leitfaden