Eine Organisationsrichtlinie anlegen oder ersetzen

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

Ersetzt das gesamte Einstellungsobjekt einer Richtlinienart. Eine Organisationsrichtlinie kann nur strenger sein als die Einstellung der Umgebung. Das Tarif-Gate wird vom Server durchgesetzt: Die Arten session und ip_allowlist sowie die AAGUID-Allowlist erfordern Enterprise (in Entwicklungsumgebungen offen). Der Inhalt der Einstellungen wird im Management-Audit-Log protokolliert; das Ereignis organization.updated enthält ihn nicht.

Anfrage

Feld Typ Pflicht Beschreibung
org_id Pfad ja Organisations-ID (org_…).
policy_kind Pfad ja Art der Richtlinie: authentication_methods, mfa, phishing_resistant, sso_enforcement, session oder ip_allowlist. Jeder andere Wert liefert 404.
If-Match Header nein Erforderlich, wenn die Richtlinie existiert (ETag des letzten Lesevorgangs); weglassen, um die Richtlinie anzulegen. * trifft auf eine bestehende Richtlinie zu.
settings Objekt ja Das Einstellungsobjekt der Art. Felder nach Art: 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 (höchstens 500); sso_enforcement: mode (off, org_context, verified_domains), connection_ids (conn_…), bypass_user_ids (usr_…, höchstens 2); session: idle_minutes, absolute_minutes, refresh_idle_days, refresh_absolute_days; ip_allowlist: cidrs (höchstens 100), applies_to (admins, all).

Anfragekörper:

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

Antwort

201 Created, wenn die Richtlinie angelegt wurde, 200 OK, wenn sie ersetzt wurde; der Body ist die Richtlinie, und die Antwort enthält deren neues 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
}

Fehler

HTTP Code Wann
400 unknown_field Der Body enthält ein Feld, das nicht im Schema steht oder nur lesbar ist.
403 plan_feature_unavailable Die Art oder die AAGUID-Allowlist erfordert einen höheren Tarif; das Problem enthält feature und required_plan.
404 not_found Die Organisation existiert nicht oder die Art ist unbekannt.
409 domain_not_verified sso_enforcement mit mode verified_domains benötigt eine verifizierte Domain der Organisation.
409 connection_test_required Das Aktivieren von sso_enforcement (von off oder ohne Richtlinie) benötigt eine erfolgreiche Testanmeldung der aktuellen Konfiguration mindestens einer der connection_ids in den letzten 24 Stunden. Führen Sie einen Verbindungstest aus (POST /v1/connections/{connection_id}:test) und versuchen Sie es erneut.
409 organization_pending_deletion Die Organisation wartet auf die Löschung im Self-Service; brechen Sie zuerst die Löschung ab.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version überein oder wurde gesendet, während keine Richtlinie dieser Art existiert, oder eine andere Anfrage hat die Richtlinie angelegt, während diese Anfrage sie anlegte; lesen Sie die Richtlinie erneut.
422 validation_failed Ein Einstellungsfeld ist unbekannt oder ungültig; errors[] verweist auf /settings/….
422 policy_weaker_than_parent Die Einstellung ist schwächer als die Einstellung der Umgebung; errors[] verweist auf das schwächere Feld.
422 at_least_one_method authentication_methods lässt keine Anmeldemethode übrig.
428 precondition_required If-Match fehlt, obwohl die Richtlinie existiert.
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder widerrufen.
403 insufficient_permissions Den Anmeldedaten fehlt die erforderliche Berechtigung.
429 rate_limited Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.

Beispiel

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