Cambios de directivas

Cómo funciona

Cada cambio requiere dos pasos. Primero lo propone: la API registra una propuesta y devuelve su lista de cambios, con el valor actual y nuevo de cada configuración, el impacto y cuándo expira la propuesta. Todavía no cambia nada en la directiva. Luego aplica la propuesta mediante su proposalId, después de que la persona responsable haya revisado la lista de cambios.

Solo la clave de API que realizó una propuesta puede leerla o aplicarla. Para una conexión OAuth, solo pueden la misma conexión y usuario. Una propuesta expira 10 minutos después de realizarse; el campo expiresAt indica la hora exacta.

Solo las directivas de Android se pueden cambiar de esta manera. Las directivas administradas por Nomid no pueden. La creación de una directiva también requiere que la empresa esté conectada a Android Enterprise.

Requisitos

• Una clave de API con el permiso POLICIES_WRITE (Cambios de directiva), combinado con POLICIES_READ. Solo un usuario del portal con permiso para editar directivas puede crear una clave con POLICIES_WRITE. Requerido por los cuatro endpoints POST y las herramientas de cambio de directiva de MCP.
• La configuración de la empresa Cambios de directiva, bajo Acceso de agentes de IA en el portal, debe estar activada. Está desactivada de forma predeterminada. Mientras esté desactivada, cada llamada de propuesta y aplicación devuelve 403. La lectura de configuraciones, revisiones y propuestas solo requiere POLICIES_READ.
• Los clientes MCP que se conectan con Iniciar sesión con Nomid en lugar de una clave de API necesitan el alcance mcp:policies:write.

Endpoints

Todas las rutas son relativas a la URL base de la API y necesitan el encabezado X-API-Key. Los cuerpos de las solicitudes son JSON.

Cuerpos de solicitud

La propuesta

Cada endpoint de propuesta y los endpoints get y apply devuelven la propuesta. Los campos más útiles:

Impacto y confirmación

Una propuesta es de impacto HIGH cuando la directiva tiene al menos un dispositivo y se cumple cualquiera de las siguientes condiciones:

• Es una reversión.
• Modifica un ajuste de alto impacto: aplicaciones de orígenes desconocidos, Google Play Protect, restablecimiento de fábrica, opciones de desarrollador, transferencia de datos por USB o cifrado del almacenamiento.
• La directiva tiene 50 o más dispositivos, sin importar el cambio.

Todo lo demás es NORMAL, incluida cada directiva nueva, ya que ningún dispositivo la usa todavía.

Las propuestas están vinculadas a una versión de la directiva

Una propuesta registra la versión de la directiva sobre la que se creó su lista de cambios. Si la directiva se vuelve a guardar antes de aplicar la propuesta, por cualquier persona y desde cualquier lugar, apply falla con 409 y el código stale_proposal, y nada cambia. Lea la directiva de nuevo, proponga de nuevo y revise la nueva lista de cambios.

Ejemplo: proponer y aplicar

Lea primero los ajustes actuales de la directiva para obtener los ID de los ajustes y los 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
    }
  ]
}

Proponer bloquear la cámara y la transferencia de datos por 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
}

Respuesta resumida. La transferencia de datos por USB es un ajuste de alto impacto y la directiva tiene dispositivos, por lo que la propuesta es de impacto HIGH y requiere confirmación. Muestre la lista de cambios a la persona responsable antes de aplicarla.

Una vez que aprueben y escriban el nombre de la directiva, aplique la propuesta con lo que hayan escrito:

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

Respuesta resumida. Los dispositivos de la directiva aplican los nuevos ajustes en su próxima sincronización.

Cuando la directiva cambió mientras tanto

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
}

Ajustes editables

Estos son los ID de configuración aceptados en los cambios, con sus valores permitidos. La etiqueta es el nombre que devuelve la API en la lista de cambios.

Al leer las configuraciones, un valor también puede ser NOT_SET (dejado al dispositivo o al valor predeterminado de Google) o CUSTOM (un valor establecido en el portal que estos valores no pueden expresar). Ninguno de los dos se puede enviar, pero ambos se pueden reemplazar por un valor permitido.

Herramientas MCP

El servidor MCP expone las mismas operaciones como herramientas. Aceptan los mismos argumentos que los endpoints REST, con policyId y proposalId como argumentos en lugar de segmentos de ruta.

Un asistente debe mostrar al usuario la lista de cambios y obtener su aprobación explícita en la conversación antes de llamar a apply_policy_proposal. Para una propuesta de impacto HIGH, debe pedirle al usuario que escriba el nombre de la política y pasar exactamente lo que escribió.

Errores

Una vez autenticada la clave de API, los errores utilizan application/problem+json con dos campos adicionales: code, un identificador estable para ramificar, y retryable, que indica si la misma solicitud se puede enviar de nuevo. Una clave faltante o no válida recibe la respuesta 401 compartida, un objeto JSON pequeño con error, message y status. Las herramientas MCP devuelven el mismo code y message como un error de herramienta.

Límites de frecuencia

Cada llamada a propose y apply cuenta para el límite de escritura de 10 solicitudes por minuto para cada clave de API o conexión de Sign in with Nomid, compartido con los endpoints de comandos del dispositivo, los códigos QR de aprovisionamiento y las herramientas de escritura de MCP. Las llamadas de lectura no cuentan para este límite.

Revisiones y reversión

Cada cambio aplicado guarda una nueva revisión de la política. Consulte la lista de revisiones para ver quién modificó la política y cuándo, y proponga una reversión para deshacer un cambio.