Crear o reemplazar una política de organización

PUT /v1/organizations/{org_id}/policies/{policy_kind} · permiso organizations:write

Reemplaza el objeto de configuración completo de un tipo de política. Una política de organización solo puede ser más estricta que la configuración del entorno. El control de plan lo aplica el servidor: los tipos session e ip_allowlist y la lista de permitidos de AAGUID requieren Enterprise (disponible en entornos de desarrollo). El contenido de la configuración se escribe en el registro de auditoría de gestión; el evento organization.updated no lo incluye.

Solicitud

Campo Tipo Obligatorio Descripción
org_id path sí ID de la organización (org_…).
policy_kind path sí Tipo de política: authentication_methods, mfa, phishing_resistant, sso_enforcement, session o ip_allowlist. Cualquier otro valor devuelve 404.
If-Match header no Obligatorio cuando la política existe (ETag de la última lectura); omítalo para crear la política. * coincide con una política existente.
settings object sí El objeto de configuración del tipo. Campos por tipo: authentication_methods: allowed_connection_ids (conn_…), allow_passkey, allow_password; mfa: required_for (none, admins, all), allowed_factors (totp, webauthn, sms, email), enrollment_grace_days (0-30); phishing_resistant: required_for, aaguid_allowlist (como máximo 500); sso_enforcement: mode (off, org_context, verified_domains), connection_ids (conn_…), bypass_user_ids (usr_…, como máximo 2); session: idle_minutes, absolute_minutes, refresh_idle_days, refresh_absolute_days; ip_allowlist: cidrs (como máximo 100), applies_to (admins, all).

Cuerpo de la solicitud:

{
  "settings": {
    "required_for": "all",
    "allowed_factors": [
      "totp",
      "webauthn"
    ],
    "enrollment_grace_days": 7
  }
}

Respuesta

201 Created cuando se creó la política, 200 OK cuando se reemplazó; el cuerpo es la política y la respuesta incluye su nuevo ETag.

{
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "policy_kind": "mfa",
  "schema_version": 1,
  "settings": {
    "required_for": "all",
    "allowed_factors": [
      "totp",
      "webauthn"
    ],
    "enrollment_grace_days": 7
  },
  "updated_at": "2026-10-12T09:30:00.123456Z",
  "version": 1
}

Errores

HTTP code Cuándo
400 unknown_field El cuerpo tiene un campo que no está en el esquema o que es de solo lectura.
403 plan_feature_unavailable El tipo o la lista de permitidos de AAGUID requiere un plan superior; el problema incluye feature y required_plan.
404 not_found La organización no existe o el tipo es desconocido.
409 domain_not_verified sso_enforcement con mode verified_domains requiere un dominio verificado en la organización.
409 connection_test_required Activar sso_enforcement (desde off o desde la ausencia de política) requiere un inicio de sesión de prueba correcto de la configuración actual de al menos uno de los connection_ids en las últimas 24 horas. Ejecute una prueba de conexión (POST /v1/connections/{connection_id}:test) e inténtelo de nuevo.
409 organization_pending_deletion La organización está pendiente de eliminación por autoservicio; cancele primero la eliminación.
412 precondition_failed If-Match no coincide con la versión actual, o se envió mientras no existe ninguna política de este tipo, o otra solicitud creó la política mientras esta la creaba; vuelva a leer la política.
422 validation_failed Un campo de configuración es desconocido o no válido; errors[] apunta a /settings/….
422 policy_weaker_than_parent La configuración es menos estricta que la del entorno; errors[] apunta al campo menos estricto.
422 at_least_one_method authentication_methods no deja ningún método de inicio de sesión.
428 precondition_required Falta If-Match mientras la política existe.
401 unauthenticated Falta la credencial, no es válida o ha sido revocada.
403 insufficient_permissions La credencial no tiene el permiso requerido.
429 rate_limited Se superó el límite de frecuencia; reintente después del periodo de Retry-After.
503 service_unavailable Una dependencia no está disponible temporalmente; reintente después del periodo de Retry-After.

Ejemplo

curl -X PUT https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/policies/mfa \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings":{"required_for":"all","allowed_factors":["totp","webauthn"]}}'