# Eine Organisationsrichtlinie in der Vorschau anzeigen

`POST /v1/organizations/{org_id}/policies/{policy_kind}:preview` · Berechtigung `organizations:write`

Bewertet ein Kandidatenobjekt für die Einstellungen, ohne es zu speichern. Der Anfragetext entspricht dem von [Erstellen oder Ersetzen einer Richtlinie](/docs/api/management/organization-policies/put), und der Server prüft ihn mit denselben Regeln und derselben Tarifprüfung. Ein Kandidat, den `PUT` ablehnen würde, wird hier daher mit demselben Problemcode abgelehnt. Es wird nichts geschrieben: keine Richtlinie, kein Audit-Eintrag und kein Ereignis. Die Anfrage nimmt weder `If-Match` noch `Idempotency-Key` entgegen, und die Antwort enthält kein `ETag`.

Die Antwort zählt die Benutzer, auf die der Kandidat angewendet wird (`basis` `users_in_scope`), nicht die Benutzer, die blockiert würden. Eine Ausnahme bildet `phishing_resistant` (siehe unten). Bedingungen, die nur bei der Anmeldung bekannt sind oder die der Richtliniendienst nicht kennt, werden nicht herausgefiltert. `not_evaluated` listet sie auf, damit die Zahl nie als mehr gelesen wird, als sie ist.

| Art | Gezählte Benutzer | `not_evaluated` |
|---|---|---|
| `authentication_methods` | Aktive Mitglieder der Organisation | `credentials` |
| `mfa` (`required_for` `admins` oder `all`) | Aktive Mitglieder der Organisation | `mfa_enrollment`; außerdem `admin_scope` für `admins` |
| `phishing_resistant` (`required_for` `admins` oder `all`) | Aktive Mitglieder der Organisation ohne akzeptierte WebAuthn-Anmeldedaten (`basis` `users_without_webauthn`, siehe unten) | `credential_policy`; außerdem `admin_scope` für `admins` |
| `sso_enforcement` `org_context` | Aktive Mitglieder der Organisation, abzüglich `bypass_user_ids` | `federated_sign_in` |
| `sso_enforcement` `verified_domains` | Aktive Mitglieder plus aktive Benutzer der Umgebung mit einer E-Mail-Adresse auf einer verifizierten Domain dieser Organisation, abzüglich `bypass_user_ids` | `federated_sign_in` |
| `session` | Aktive Mitglieder der Organisation | keine |
| `ip_allowlist` | Aktive Mitglieder der Organisation | `client_ip`; außerdem `admin_scope` für `admins` |

Bei `phishing_resistant` sind Anzahl und Stichprobe die Benutzer im Geltungsbereich, die sich heute nicht phishing-resistent anmelden können: Benutzer ohne aktive WebAuthn-Anmeldedaten (ein Passkey oder ein Sicherheitsschlüssel mit einem ersten Faktor), die die AAGUID-Allowlist akzeptiert. Die Allowlist ist die des Kandidaten, oder die der Umgebung, wenn die des Kandidaten leer ist. Bei einer Allowlist zählen Anmeldedaten nur, wenn ihr Modell aufgeführt ist und ihre Attestierung verifiziert wurde. Ausstehende, widerrufene und als Klon verdächtigte Anmeldedaten zählen nicht. `credential_policy` bedeutet, dass die Attestierungsanforderung der Umgebung, die Regel für gerätegebundene Passkeys und der Modellstatus des Authenticators nicht angewendet werden. Die Zahl kann daher niedriger ausfallen als die Anzahl der Benutzer, die blockiert würden. Umfasst der Geltungsbereich mehr als 10.000 Benutzer, fällt die Antwort auf `users_in_scope` mit `passkey_enrollment` zurück. Können die Daten der Anmeldedaten nicht gelesen werden, schlägt die Anfrage mit `503` fehl, und es wird keine Zahl zurückgegeben.

`required_for` `none` und `mode` `off` zählen niemanden. Ein aktives Mitglied ist ein Mitglied, dessen Mitgliedschaft aktiv ist und dessen Benutzer nicht gesperrt ist. Jeder Benutzer wird einmal gezählt. `admin_scope` bedeutet, dass `admins` als alle Mitglieder gezählt wird, so wie die Anmeldung es heute anwendet. Die Benutzer einer anderen Organisation oder einer anderen Umgebung werden nie gezählt.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `org_id` | Pfad | ja | Organisations-ID (`org_…`). |
| `policy_kind` | Pfad | ja | Richtlinienart: `authentication_methods`, `mfa`, `phishing_resistant`, `sso_enforcement`, `session` oder `ip_allowlist`. Jeder andere Wert liefert `404`. |
| `settings` | Objekt | ja | Das Kandidatenobjekt der Einstellungen dieser Art, mit denselben Feldern wie bei `PUT`. |

Anfragetext:

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

## Antwort

`200 OK`. `sample` enthält höchstens 20 Benutzer der gezählten Menge, sortiert nach ID, nur mit der Benutzer-ID.

| Feld | Typ | Beschreibung |
|---|---|---|
| `organization_id` | string | Organisations-ID (`org_…`). |
| `policy_kind` | string | Die angezeigte Art. |
| `basis` | string | Was `affected_count` zählt: `users_in_scope` oder, für `phishing_resistant`, `users_without_webauthn`. Es können neue Werte hinzukommen. |
| `affected_count` | integer | Anzahl der Benutzer, die `basis` zählt. |
| `sample` | array | Höchstens 20 Objekte mit `user_id` (`usr_…`). |
| `not_evaluated` | array | Bedingungen, die die Zählung nicht filtert: `admin_scope`, `credentials`, `mfa_enrollment`, `passkey_enrollment`, `federated_sign_in`, `client_ip`, `credential_policy`. Es können neue Werte hinzukommen. |

```json
{
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "policy_kind": "mfa",
  "basis": "users_in_scope",
  "affected_count": 2,
  "sample": [
    {
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4b"
    },
    {
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4c"
    }
  ],
  "not_evaluated": [
    "mfa_enrollment"
  ]
}
```

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 400 | `unknown_field` | Der Anfragetext enthält ein Feld, das nicht im Schema steht. |
| 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` erfordert eine verifizierte Domain für die Organisation. |
| 409 | `connection_test_required` | Das Einschalten von `sso_enforcement` (von `off` oder ohne Richtlinie) erfordert eine erfolgreiche Test-Anmeldung der aktuellen Konfiguration bei mindestens einem der `connection_ids` in den letzten 24 Stunden. Führen Sie einen Verbindungstest (`POST /v1/connections/{connection_id}:test`) aus und versuchen Sie es erneut. |
| 409 | `organization_pending_deletion` | Die Organisation wartet auf die selbstständige Löschung. |
| 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. |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Die Anmeldedaten haben nicht die erforderliche Berechtigung. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach Ablauf des Zeitraums `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar (bei `phishing_resistant` auch, wenn die Daten der Anmeldedaten nicht gelesen werden können); wiederholen Sie die Anfrage nach Ablauf des Zeitraums `Retry-After`. |

## Beispiel

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

```bash
keenauth organizations policies preview org_01j9xk3m7q8r2s4t6v8w0y2z4a mfa \
  --data '{"settings":{"required_for":"all","allowed_factors":["totp","webauthn"]}}'
```