Policy changes

How it works

Every change takes two steps. First you propose it: the API records a proposal and returns its change list, with each setting's current and new value, the impact and when the proposal expires. Nothing changes on the policy yet. Then you apply the proposal by its proposalId, after the person responsible has reviewed the change list.

Only the API key that made a proposal can read or apply it. For an OAuth connection, only the same connection and user can. A proposal expires 10 minutes after it is made; the expiresAt field gives the exact time.

Only Android policies can be changed this way. Policies managed by Nomid cannot. Creating a policy also requires the company to be connected to Android Enterprise.

Requirements

• An API key with the POLICIES_WRITE permission (Policy changes), combined with POLICIES_READ. Only a portal user with permission to edit policies can create a key with POLICIES_WRITE. Required by the four POST endpoints and the MCP policy change tools.
• The company setting Policy changes, under AI agent access in the portal, must be turned on. It is off by default. While it is off, every proposal and apply call returns 403. Reading settings, revisions and proposals needs POLICIES_READ only.
• MCP clients that connect with OAuth instead of an API key need the mcp:policies:write scope.

Endpoints

All paths are relative to the API base URL and need the X-API-Key header. Request bodies are JSON.

Request bodies

The proposal

Every propose endpoint and the get and apply endpoints return the proposal. The most useful fields:

Impact and confirmation

A proposal is HIGH impact when the policy has at least one device and any of these is true:

• It is a rollback.
• It changes a high-impact setting: apps from unknown sources, Google Play Protect, factory reset, developer options, USB data transfer or storage encryption.
• The policy has 50 or more devices, whatever the change.

Everything else is NORMAL, including every new policy, since no device uses it yet.

Proposals are pinned to a policy version

A proposal records the policy version its change list was built on. If the policy is saved again before you apply the proposal, by anyone and from anywhere, apply fails with 409 and code stale_proposal, and nothing changes. Read the policy again, propose again and review the new change list.

Example: propose and apply

Read the policy's current settings first, to get the setting IDs and allowed values:

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

Propose blocking the camera and USB data transfer:

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
}

Abridged response. USB data transfer is a high-impact setting and the policy has devices, so the proposal is HIGH impact and requires confirmation. Show the change list to the person responsible before applying it.

Once they approve and type the policy's name, apply the proposal with what they typed:

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

Abridged response. Devices on the policy apply the new settings on their next sync.

When the policy changed in the meantime

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
}

Editable settings

These are the setting IDs accepted in changes, with their allowed values. The label is the name the API returns in the change list.

When reading settings, a value can also be NOT_SET (left to the device or Google's default) or CUSTOM (a value set in the portal that these values cannot express). Neither can be sent, but both can be replaced with an allowed value.

MCP tools

The MCP server exposes the same operations as tools. They take the same arguments as the REST endpoints, with policyId and proposalId as arguments instead of path segments.

An assistant must show the user the change list and get their explicit approval in the conversation before it calls apply_policy_proposal. For a HIGH impact proposal it must ask the user to type the policy's name and pass exactly what they typed.

MCP server

Errors

Once the API key is authenticated, errors use application/problem+json with two extra fields: code, a stable identifier to branch on, and retryable, which says whether the same request can be sent again. A missing or invalid key gets the shared 401 response, a small JSON object with error, message and status. MCP tools return the same code and message as a tool error.

Rate limits

Each propose and apply call counts toward the per-key write limit of 10 requests per minute, shared with the device command endpoints and the MCP write tools. Read calls do not count toward it.

Revisions and rollback

Every applied change saves a new revision of the policy. List revisions to see who changed the policy and when, and propose a rollback to undo a change.