Modifications de stratégie

Comment ça fonctionne

Chaque modification se déroule en deux étapes. D'abord, vous la proposez : l'API enregistre une proposition et renvoie sa liste de modifications, avec la valeur actuelle et la nouvelle valeur de chaque paramètre, l'impact et la date d'expiration de la proposition. Rien ne change encore sur la stratégie. Ensuite, vous appliquez la proposition par son proposalId, après que la personne responsable a examiné la liste de modifications.

Seule la clé d'API ayant créé une proposition peut la lire ou l'appliquer. Pour une connexion OAuth, seuls la même connexion et le même utilisateur le peuvent. Une proposition expire 10 minutes après avoir été créée ; le champ expiresAt indique l'heure exacte.

Seules les stratégies Android peuvent être modifiées de cette manière. Les stratégies gérées par Nomid ne le peuvent pas. La création d'une stratégie nécessite également que l'entreprise soit connectée à Android Enterprise.

Prérequis

• Une clé d'API avec l'autorisation POLICIES_WRITE (Modifications de stratégie), combinée avec POLICIES_READ. Seul un utilisateur du portail autorisé à modifier des stratégies peut créer une clé avec POLICIES_WRITE. Requis par les quatre points de terminaison POST et les outils MCP de modification de stratégie.
• Le paramètre d'entreprise Modifications de stratégie, sous Accès des agents IA dans le portail, doit être activé. Il est désactivé par défaut. Tant qu'il est désactivé, chaque appel pour proposer ou appliquer renvoie 403. La lecture des paramètres, des révisions et des propositions nécessite uniquement POLICIES_READ.
• Les clients MCP qui se connectent avec « Se connecter avec Nomid » au lieu d'une clé d'API ont besoin de la portée mcp:policies:write.

Points de terminaison

Tous les chemins sont relatifs à l'URL de base de l'API et nécessitent l'en-tête X-API-Key. Les corps des requêtes sont en JSON.

Corps de requête

La proposition

Chaque point de terminaison de proposition ainsi que les points de terminaison get et apply renvoient la proposition. Les champs les plus utiles :

Impact et confirmation

Une proposition a un impact HIGH lorsque la politique compte au moins un appareil et que l'une des conditions suivantes est remplie :

• Il s'agit d'un retour arrière (rollback).
• Elle modifie un paramètre à fort impact : applications de sources inconnues, Google Play Protect, réinitialisation aux paramètres d'usine, options pour les développeurs, transfert de données USB ou chiffrement du stockage.
• La politique compte 50 appareils ou plus, quelle que soit la modification.

Tout le reste est NORMAL, y compris toute nouvelle politique, car aucun appareil ne l'utilise encore.

Les propositions sont associées à une version de politique

Une proposition enregistre la version de la politique sur laquelle sa liste de modifications a été créée. Si la politique est enregistrée à nouveau avant que vous n'appliquiez la proposition, par n'importe qui et depuis n'importe où, l'application échoue avec une erreur 409 et le code stale_proposal, et rien ne change. Lisez à nouveau la politique, proposez à nouveau et examinez la nouvelle liste des modifications.

Exemple : proposer et appliquer

Lisez d'abord les paramètres actuels de la politique pour obtenir les identifiants de paramètres et les valeurs autorisées :

curl "https://api.nomid.tech/emm/api/v1/policies/p7k2m9qa4xz/settings" \
  -H "X-API-Key: $NOMID_API_KEY"

{
  "policyId": "p7k2m9qa4xz",
  "displayName": "Warehouse scanners",
  "version": 12,
  "deviceCount": 18,
  "editable": true,
  "settings": [
    {
      "id": "CAMERA",
      "label": "Camera",
      "group": "RESTRICTIONS",
      "value": "ALLOW",
      "allowedValues": ["ALLOW", "BLOCK"],
      "highImpact": false
    }
  ]
}

Proposez de bloquer l'appareil photo et le transfert de données USB :

curl -X POST "https://api.nomid.tech/emm/api/v1/policies/p7k2m9qa4xz/changes" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"changes": [{"setting": "CAMERA", "value": "BLOCK"}, {"setting": "USB_DATA_ACCESS", "value": "BLOCK"}]}'

HTTP/1.1 201 Created

{
  "capability": "update_policy_settings",
  "status": "PENDING",
  "title": "Edit policy settings",
  "summary": "Change 2 settings of policy \"Warehouse scanners\". 18 devices apply it on their next sync. High impact: type the policy's name to confirm.",
  "target": { "kind": "policy", "id": "p7k2m9qa4xz", "name": "Warehouse scanners" },
  "fields": [
    { "label": "Camera", "value": "BLOCK", "previousValue": "ALLOW" },
    { "label": "USB data transfer", "value": "BLOCK", "previousValue": "ALLOW" }
  ],
  "expiresAt": "2026-10-09T14:40:00Z",
  "impact": "HIGH",
  "proposalId": "prp_7GQv2LkR9sTn4WxY8bZcA1dE",
  "requiresConfirmation": true
}

Réponse abrégée. Le transfert de données USB est un paramètre à fort impact et la politique comporte des appareils, la proposition a donc un impact HIGH et nécessite une confirmation. Présentez la liste des modifications à la personne responsable avant de l'appliquer.

Une fois qu'elle a approuvé et saisi le nom de la politique, appliquez la proposition avec ce qu'elle a saisi :

curl -X POST "https://api.nomid.tech/emm/api/v1/policy-proposals/prp_7GQv2LkR9sTn4WxY8bZcA1dE/apply" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation": "Warehouse scanners"}'

HTTP/1.1 200 OK

{
  "capability": "update_policy_settings",
  "status": "SUCCEEDED",
  "impact": "HIGH",
  "proposalId": "prp_7GQv2LkR9sTn4WxY8bZcA1dE",
  "requiresConfirmation": true,
  "result": {
    "policyId": "p7k2m9qa4xz",
    "displayName": "Warehouse scanners",
    "version": 13,
    "message": "Policy settings changed. Devices on the policy apply them on their next sync."
  }
}

Réponse abrégée. Les appareils soumis à la politique appliquent les nouveaux paramètres lors de leur prochaine synchronisation.

Lorsque la politique a été modifiée entre-temps

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

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Policy \"Warehouse scanners\" was changed after this proposal was made. Nothing was applied: read it again and propose again.",
  "instance": "/emm/api/v1/policy-proposals/prp_7GQv2LkR9sTn4WxY8bZcA1dE/apply",
  "code": "stale_proposal",
  "retryable": false
}

Paramètres modifiables

Voici les identifiants de paramètres acceptés dans les modifications, ainsi que leurs valeurs autorisées. Le libellé correspond au nom renvoyé par l'API dans la liste des modifications.

Lors de la lecture des paramètres, une valeur peut également être NOT_SET (laissée à la valeur par défaut de l'appareil ou de Google) ou CUSTOM (une valeur définie dans le portail que ces valeurs ne peuvent pas exprimer). Aucune des deux ne peut être envoyée, mais toutes deux peuvent être remplacées par une valeur autorisée.

Outils MCP

Le serveur MCP expose les mêmes opérations sous forme d'outils. Ils prennent les mêmes arguments que les points de terminaison REST, avec policyId et proposalId comme arguments au lieu de segments de chemin.

Un assistant doit présenter la liste des modifications à l'utilisateur et obtenir son approbation explicite dans la conversation avant d'appeler apply_policy_proposal. Pour une proposition d'impact HIGH, il doit demander à l'utilisateur de saisir le nom de la règle et transmettre exactement ce qu'il a saisi.

Erreurs

Une fois la clé d'API authentifiée, les erreurs utilisent application/problem+json avec deux champs supplémentaires : code, un identifiant stable sur lequel baser les branchements, et retryable, qui indique si la même requête peut être renvoyée. Une clé manquante ou non valide reçoit la réponse 401 partagée, un petit objet JSON comportant error, message et status. Les outils MCP renvoient les mêmes code et message sous la forme d'une erreur d'outil.

Limites de débit

Chaque appel propose et apply est décompté de la limite d'écriture de 10 requêtes par minute pour chaque clé d'API ou connexion Sign in with Nomid, partagée avec les points de terminaison de commande d'appareils, les codes QR de provisionnement et les outils d'écriture MCP. Les appels de lecture ne sont pas décomptés.

Révisions et rollback

Chaque modification appliquée enregistre une nouvelle révision de la politique. Listez les révisions pour voir qui a modifié la politique et quand, et proposez un rollback pour annuler une modification.