Bereitstellungs-QR-Codes

Erstellen Sie einen QR-Code, der ein neues oder auf die Werkseinstellungen zurückgesetztes Android-Gerät mit einer bestimmten Richtlinie in Ihrem Unternehmen registriert.

So funktioniert es

Jede Anfrage erstellt ein neues Registrierungstoken für die Richtlinie und gibt einen QR-Code zurück, der dieses enthält. Der Code funktioniert 24 Stunden nach seiner Erstellung nicht mehr; die Antwort gibt den genauen Zeitpunkt in expiresAt an. Erstellen Sie einen Code, wenn jemand im Begriff ist, Geräte einzurichten, und erstellen Sie einen neuen, anstatt einen älteren wiederzuverwenden.

Um den Code zu verwenden, tippen Sie sechsmal auf den Startbildschirm des Einrichtungsassistenten des Geräts, stellen Sie bei Aufforderung eine Verbindung zum WLAN her und scannen Sie ihn. Ein Gerät kann auf diese Weise nur registriert werden, wenn es neu ist oder auf die Werkseinstellungen zurückgesetzt wurde.

VR-only-Richtlinien können nicht mit einem QR-Code bereitgestellt werden: Ihre Geräte werden mit Nomid Ops über USB bereitgestellt.

Voraussetzungen

Ein API-Schlüssel mit der Berechtigung PROVISIONING, kombiniert mit POLICIES_READ. Nur ein Portal-Benutzer, der Geräte bereitstellen darf und Zugriff auf alle Richtlinien hat, kann einen Schlüssel mit PROVISIONING erstellen.
Das Unternehmen muss seine Registrierung bei Android Enterprise abgeschlossen haben.
MCP-Clients, die sich mit „Sign in with Nomid“ anstelle eines API-Schlüssels verbinden, benötigen den Scope mcp:provisioning, und die Bereitstellungseinstellung des Unternehmens unter „AI agent access“ im Portal muss aktiviert sein.

Endpunkt

Der Pfad ist relativ zur API-Basis-URL und erfordert den X-API-Key-Header. Eine erfolgreiche Anfrage gibt 201 Created zurück.

Methode	Endpunkt	Beschreibung
POST	/policies/{policyId}/provisioning-qr-codes	Erstellen Sie einen Bereitstellungs-QR-Code für eine Richtlinie mit einem neuen Registrierungstoken

Request-Body

Jedes Feld ist optional: Senden Sie ein leeres JSON-Objekt für einen Code ohne WLAN und mit der standardmäßigen persönlichen Nutzung. Ein unbekanntes Feld gibt 400 zurück.

Feld	Werte	Beschreibung
personalUsage	UNSPECIFIED, ALLOWED, DISALLOWED, USERLESS	Wie das Gerät verwendet wird: ALLOWED für ein Arbeitsprofil auf einem Gerät in Privateigentum, DISALLOWED für ein vollständig verwaltetes unternehmenseigenes Gerät, USERLESS für ein dediziertes Gerät ohne Benutzerkonto. UNSPECIFIED ist der Standardwert, wenn nichts angegeben ist.
wifiSsid		Ein WLAN-Netzwerk, mit dem sich das Gerät während der Einrichtung verbindet. Bis zu 32 Bytes in UTF-8. Leerzeichen am Anfang oder Ende bleiben als Teil des Namens erhalten.
wifiPassword		Das Passwort von wifiSsid, bis zu 63 Bytes in UTF-8. Ein WPA-Passwort hat mindestens 8 Bytes. Ein WEP-Schlüssel besteht aus 5 oder 13 ASCII-Zeichen bzw. 10 oder 26 Hexadezimalziffern. Wird niemals zurückgegeben.
wifiSecurity	NONE, WPA, WEP	Der Sicherheitstyp von wifiSsid. Standardmäßig WPA, wenn ein Passwort angegeben ist, andernfalls NONE. NONE erfordert kein Passwort, WPA und WEP erfordern eines.
wifiHidden		Gibt an, ob wifiSsid ein verborgenes Netzwerk ist. Standardmäßig false.

wifiPassword, wifiSecurity und wifiHidden erfordern wifiSsid.

Antwort

Feld	Beschreibung
policyId	Der Pfadname der Richtlinie, die policyId, mit der sich Geräte registrieren.
policyName	Der Anzeigename der Richtlinie.
personalUsage	Der Modus für die persönliche Nutzung des Registrierungstokens.
expiresAt	Wann der QR-Code die Registrierung von Geräten beendet.
wifiSsid	Das WLAN-Netzwerk, mit dem sich das Gerät während der Einrichtung verbindet. Wird weggelassen, wenn keines angegeben wurde.
image	Das QR-Code-Bild: mimeType (image/png) und data, die Bild-Bytes in Base64.
portalUrl	Ein Link zur Richtlinie im Nomid-Portal.

Beispiel

Erstellen Sie einen Code für ein vollständig verwaltetes Gerät, das sich während der Einrichtung mit einem WPA-Netzwerk verbindet. jq erstellt den Body aus einer Umgebungsvariable, sodass das Passwort ordnungsgemäß maskiert wird und nicht in Ihrem Shell-Verlauf landet.

curl -X POST "https://api.nomid.tech/emm/api/v1/policies/p7k2m9qa4xz/provisioning-qr-codes" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg password "$WIFI_PASSWORD" \
    '{personalUsage: "DISALLOWED", wifiSsid: "Warehouse", wifiPassword: $password}')"

HTTP/1.1 201 Created

{
  "policyId": "p7k2m9qa4xz",
  "policyName": "Warehouse scanners",
  "personalUsage": "DISALLOWED",
  "expiresAt": "2026-10-11T14:30:00Z",
  "wifiSsid": "Warehouse",
  "image": {
    "mimeType": "image/png",
    "data": "iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "portalUrl": "https://portal.nomid.tech/#/acme/acme/policy/p7k2m9qa4xz"
}

Dekodieren Sie data aus Base64, um das PNG zu erhalten. Die Bilddaten sind hier gekürzt dargestellt.

Fehler: VR-only-Richtlinie

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Policy q4vr8headset is a VR-only policy: its devices are provisioned with Nomid Ops over USB, not with a QR code.",
  "instance": "/emm/api/v1/policies/q4vr8headset/provisioning-qr-codes",
  "code": "unsupported",
  "retryable": false
}

Fehler

Sobald der API-Schlüssel authentifiziert ist, verwenden Fehler application/problem+json mit zwei zusätzlichen Feldern: code, eine stabile Kennung zur Verzweigung, und retryable, das angibt, ob dieselbe Anfrage erneut gesendet werden kann. Ein nicht lesbarer Body ist die Ausnahme, die in der 400-Zeile beschrieben wird. Ein fehlender oder ungültiger Schlüssel erhält die gemeinsame 401-Antwort, ein kleines JSON-Objekt mit error, message und status. Das MCP-Tool gibt denselben Code und dieselbe Nachricht als Tool-Fehler zurück.

Status	Code	Bedeutung
400	invalid_arguments	Eine Option ist ungültig: ein unbekannter personalUsage- oder wifiSecurity-Wert, ein WLAN-Feld ohne wifiSsid oder ein WLAN-Name, Passwort oder Sicherheitstyp, der den oben genannten Regeln nicht entspricht. Das Detail gibt an, welcher. Ein Body, der kein gültiges JSON ist oder ein unbekanntes Feld enthält, gibt ebenfalls 400 zurück, als Problem Details ohne code oder retryable.
401	-	Der API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403	forbidden	Dem Schlüssel fehlt PROVISIONING oder POLICIES_READ.
404	not_found	Keine Richtlinie mit dieser policyId im Unternehmen des Schlüssels vorhanden.
409	unsupported	Die Richtlinie kann Geräte nicht per QR-Code bereitstellen: Es handelt sich um eine reine VR-Richtlinie oder das Unternehmen hat seine Android Enterprise-Registrierung noch nicht abgeschlossen.
422	refused	Die Richtlinie wurde gelöscht.
429	rate_limited	Zu viele Schreibanfragen für diesen Schlüssel. Der Header Retry-After und das Detail geben die Sekunden an, die gewartet werden müssen. retryable ist true.
502	provider_error	Google hat das Registrierungstoken nicht erstellt. Es wurde kein QR-Code erstellt. retryable ist true: Versuchen Sie es gleich noch einmal.

Ratenbegrenzungen

Jede Anfrage zählt für das Schreiblimit von 10 Anfragen pro Minute pro Schlüssel, geteilt mit den Endpunkten für Gerätebefehle und Richtlinienänderungen sowie den MCP-Schreib-Tools. Eine „Sign in with Nomid“-Verbindung, die create_provisioning_qr_code aufruft, beansprucht dasselbe Limit, gezählt pro Verbindung. Anfragen, die bei den Berechtigungsprüfungen oder der Argumentvalidierung fehlschlagen, zählen nicht.

MCP-Tool

Das MCP-Tool create_provisioning_qr_code akzeptiert dieselben Optionen mit policyId als Argument. Es gibt den QR-Code als MCP-Bildblock zurück, sodass der Assistent ihn dem Benutzer anzeigen kann, ohne ihn zu lesen.

MCP-Server