# 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:

```json
{
  "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`.

```json
{
  "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

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