Alterações de política

Como funciona

Cada alteração requer duas etapas. Primeiro, você a propõe: a API registra uma proposta e retorna sua lista de alterações, com o valor atual e o novo de cada configuração, o impacto e quando a proposta expira. Nada muda na política ainda. Em seguida, você aplica a proposta por meio do proposalId dela, depois que a pessoa responsável tiver revisado a lista de alterações.

Apenas a chave de API que fez uma proposta pode lê-la ou aplicá-la. Para uma conexão OAuth, apenas a mesma conexão e usuário podem. Uma proposta expira 10 minutos após ser feita; o campo expiresAt informa o horário exato.

Apenas políticas Android podem ser alteradas dessa forma. Políticas gerenciadas pelo Nomid não podem. Criar uma política também exige que a empresa esteja conectada ao Android Enterprise.

Requisitos

• Uma chave de API com a permissão POLICIES_WRITE (Alterações de política), combinada com POLICIES_READ. Apenas um usuário do portal com permissão para editar políticas pode criar uma chave com POLICIES_WRITE. Obrigatório para os quatro endpoints POST e as ferramentas de alteração de política do MCP.
• A configuração da empresa Alterações de política, em Acesso de agente de IA no portal, precisa estar ativada. Ela vem desativada por padrão. Enquanto estiver desativada, toda chamada de proposta e aplicação retornará 403. A leitura de configurações, revisões e propostas requer apenas POLICIES_READ.
• Clientes MCP que se conectam com Sign in with Nomid em vez de uma chave de API precisam do escopo mcp:policies:write.

Endpoints

Todos os caminhos são relativos ao URL base da API e exigem o cabeçalho X-API-Key. Os corpos das requisições são em JSON.

Corpos de requisição

A proposta

Todos os endpoints propose e os endpoints get e apply retornam a proposta. Os campos mais úteis:

Impacto e confirmação

Uma proposta é de impacto HIGH quando a política tem pelo menos um dispositivo e qualquer um destes for verdadeiro:

• É uma reversão.
• Altera uma configuração de alto impacto: aplicativos de fontes desconhecidas, Google Play Protect, restauração de fábrica, opções do desenvolvedor, transferência de dados USB ou criptografia de armazenamento.
• A política tem 50 ou mais dispositivos, independentemente da alteração.

Todo o resto é NORMAL, incluindo qualquer nova política, já que nenhum dispositivo a utiliza ainda.

As propostas são vinculadas a uma versão da política

Uma proposta registra a versão da política na qual sua lista de alterações foi baseada. Se a política for salva novamente antes de você aplicar a proposta, por qualquer pessoa e de qualquer lugar, a aplicação falha com 409 e o código stale_proposal, e nada é alterado. Leia a política novamente, proponha novamente e revise a nova lista de alterações.

Exemplo: propor e aplicar

Leia primeiro as configurações atuais da política para obter os IDs de configuração e os valores permitidos:

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

Proponha bloquear a câmera e a transferência de dados 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
}

Resposta resumida. A transferência de dados USB é uma configuração de alto impacto e a política tem dispositivos, portanto a proposta é de impacto HIGH e requer confirmação. Mostre a lista de alterações à pessoa responsável antes de aplicá-la.

Depois que ela aprovar e digitar o nome da política, aplique a proposta com o que foi digitado:

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

Resposta resumida. Os dispositivos na política aplicam as novas configurações na próxima sincronização.

Quando a política foi alterada nesse ínterim

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
}

Configurações editáveis

Estes são os IDs de configuração aceitos em alterações, com seus valores permitidos. O rótulo é o nome que a API retorna na lista de alterações.

Ao ler configurações, um valor também pode ser NOT_SET (deixado para o dispositivo ou padrão do Google) ou CUSTOM (um valor definido no portal que estes valores não podem expressar). Nenhum dos dois pode ser enviado, mas ambos podem ser substituídos por um valor permitido.

Ferramentas MCP

O servidor MCP expõe as mesmas operações como ferramentas. Elas recebem os mesmos argumentos que os endpoints REST, com policyId e proposalId como argumentos em vez de segmentos de caminho.

Um assistente deve mostrar ao usuário a lista de alterações e obter sua aprovação explícita na conversa antes de chamar apply_policy_proposal. Para uma proposta de ALTO impacto, ele deve pedir que o usuário digite o nome da política e passar exatamente o que ele digitou.

Erros

Depois que a chave de API é autenticada, os erros usam application/problem+json com dois campos extras: code, um identificador estável para ramificação, e retryable, que indica se a mesma solicitação pode ser enviada novamente. Uma chave ausente ou inválida recebe a resposta 401 compartilhada, um pequeno objeto JSON com error, message e status. As ferramentas MCP retornam os mesmos code e message como um erro de ferramenta.

Limites de taxa

Cada chamada de propose e apply conta para o limite de gravação de 10 solicitações por minuto para cada chave de API ou conexão Sign in with Nomid, compartilhado com os endpoints de comando de dispositivo, códigos QR de provisionamento e as ferramentas de gravação do MCP. Chamadas de leitura não contam para o limite.

Revisões e rollback

Cada alteração aplicada salva uma nova revisão da política. Liste as revisões para ver quem alterou a política e quando, e proponha um rollback para desfazer uma alteração.