# Aktualisiere die Identitätseinstellungen

`PATCH /v1/identity-settings` · Berechtigung `identity-settings:write`

Aktualisiert die Benutzernamen-Einstellungen der Umgebung mit einem JSON-Merge-Patch (`application/merge-patch+json`, RFC 7396). `If-Match` ist erforderlich: fehlt er, folgt `428`, bei veralteter Version `412`. Wurden die Einstellungen nie geschrieben, ist die Version `"0"` und der erste Schreibvorgang legt die Zeile an. Ein Patch, der nichts ändert, schreibt nichts und behält die Version.

## Anfrage

| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| `If-Match` | header | ja | Das `ETag` der Einstellungen wie zuletzt gelesen (`"0"`, wenn nie geschrieben). Fehlt: `428`; veraltet: `412`. |
| `username_identifier` | string | nein | `required`, `optional` oder `off`. Darf nicht `null` sein. |
| `username_min_length` | integer | nein | 3–64, nicht größer als `username_max_length`. Darf nicht `null` sein. |
| `username_max_length` | integer | nein | 3–64, nicht kleiner als `username_min_length`. Darf nicht `null` sein. |
| `reserved_usernames` | string[] \| null | nein | Höchstens 1000 Namen; ersetzt die gesamte Liste (RFC 7396 führt Arrays nicht zusammen). `null` oder `[]` leert sie. Jeder Eintrag wird normalisiert, Duplikate entfallen und die Liste wird sortiert gespeichert. |
| `verification_policy` | string | nein | `before_sign_in` (Standard) oder `after_sign_in`. `after_sign_in` stoppt die Bereinigung unbestätigter Konten. Darf nicht `null` sein. |
| `unverified_account_ttl_days` | integer | nein | 1-30 (Standard 7): Tage, die eine unbestätigte Registrierung in einer `before_sign_in`-Umgebung aufbewahrt wird, bevor sie gelöscht wird. Darf nicht `null` sein. |

Die Benutzernamen-Einstellungen gelten nur für spätere Schreibvorgänge; bestehende Benutzer werden durch sie nie geändert. Die Verifizierungseinstellungen wirken auch auf bestehende Registrierungen (siehe unten).

## Durchsetzungsregeln

- `off` (Standard): Eine Anfrage, die einen Benutzernamen schreibt (`POST /v1/users`, `PATCH /v1/users/{id}`), scheitert mit `422` und dem Code `identifier_type_disabled` (Zeiger `/username`). Das Entfernen eines bestehenden Benutzernamens bleibt erlaubt, und ein Benutzer-Patch, der den Benutzernamen nicht berührt, wird nicht erneut geprüft. Die Anmeldung löst Konten nicht über den Benutzernamen auf.
- `optional`: Ein Benutzername kann gesetzt werden. `required`: Das Anlegen eines Benutzers über die Management-API ohne Benutzernamen scheitert mit `422` (`required`), und ein Management-Patch kann ihn nicht entfernen. Die Abfrage des Benutzernamens im Registrierungsformular ist Sache der gehosteten Anmeldung; Social- und Just-in-Time-Anlage fragen nie danach.
- Länge: Ein Benutzername, der kürzer als `username_min_length` oder länger als `username_max_length` ist, scheitert mit `422` (`invalid`).
- Reservierte Namen: Ein Benutzername, dessen normalisierte Form in `reserved_usernames` steht, scheitert mit `422` und dem Code `username_reserved`. Ein ungültiger Listeneintrag scheitert mit `422` und dem Zeiger `/reserved_usernames/<i>`.
- Bestehende Benutzer werden bei einer Änderung der Einstellung nicht geändert; die Regeln gelten nur für spätere Schreibvorgänge.

## Bereinigung unbestätigter Konten

`verification_policy` und `unverified_account_ttl_days` steuern die automatische Bereinigung nie bestätigter Registrierungen. Die Bereinigung läuft nur, solange die E-Mail-Adresse (oder die Telefonnummer) eine erforderliche Kennung ist; für E-Mail ist das der Standard.

- `before_sign_in` (Standard): Ein durch Registrierung erstellter Benutzer erhält keine Token, bevor er die erforderliche Kennung bestätigt hat. Ein registrierter Benutzer, der `unverified_account_ttl_days` Tage (1-30, Standard 7) nach der Registrierung noch keine bestätigte E-Mail-Adresse oder Telefonnummer hat, nie ein Token erhalten hat und keine soziale oder Unternehmensidentität (SAML/OIDC) besitzt, wird endgültig gelöscht. Die Bereinigung läuft regelmäßig (standardmäßig stündlich).
- `after_sign_in`: Benutzer erhalten Token vor der Bestätigung (`email_verified: false`); die Bereinigung läuft nicht und kein Benutzer wird gelöscht.
- Nie gelöscht werden: Benutzer, die über die Management-API, den Import, SCIM, eine Einladung oder Just-in-Time-Föderation erstellt wurden, gesperrte Benutzer und Benutzer, deren Löschung bereits begonnen hat. Nur Registrierungen, die nach dem Start der Bereinigung in der Umgebung erstellt wurden, kommen in Frage.
- Die Löschung ist endgültig: Der Benutzer wird hart gelöscht, ein Grabstein mit dem Grund `unverified_expired` bleibt erhalten und das Ereignis `user.deleted` wird veröffentlicht.
- Eine Änderung der Richtlinie oder der Frist wirkt ab dem nächsten Lauf. Wird `unverified_account_ttl_days` verringert, kommen ältere unbestätigte Registrierungen sofort in Frage; beim Wechsel von `after_sign_in` zurück zu `before_sign_in` werden abgelaufene unbestätigte Registrierungen beim nächsten Lauf gelöscht.

## Antwort

`200 OK` mit den aktualisierten Einstellungen und dem neuen `ETag`.

```json
{
  "username_identifier": "optional",
  "username_min_length": 3,
  "username_max_length": 32,
  "reserved_usernames": ["admin", "root", "support"],
  "verification_policy": "before_sign_in",
  "unverified_account_ttl_days": 7,
  "updated_at": "2026-10-05T09:30:00.123456Z"
}
```

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 400 | `unknown_field` | Der Patch enthält ein unbekanntes oder schreibgeschütztes Feld oder ist kein JSON-Objekt (`malformed_request`). |
| 412 | `precondition_failed` | `If-Match` stimmt nicht mit der aktuellen Version überein. |
| 415 | `unsupported_media_type` | Der Content-Type ist nicht `application/merge-patch+json`. |
| 422 | `validation_failed` | Ein Wert ist ungültig, `min` ist größer als `max`, oder ein Feld, das nicht `null` sein darf, wurde auf `null` gesetzt (`code: invalid`). |
| 428 | `precondition_required` | Der `If-Match`-Header fehlt. |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder wurden widerrufen. |
| 403 | `insufficient_permissions` | Die Anmeldedaten haben nicht die erforderliche Berechtigung. |
| 429 | `rate_limited` | Die Rate-Grenze wurde überschritten; Wiederhole nach dem `Retry-After`-Zeitraum. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; Wiederhole nach dem `Retry-After`-Zeitraum. |

## Beispiel

```bash
curl -X PATCH https://api.eu.keenauth.com/v1/identity-settings \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "0"' \
  -d '{"username_identifier":"optional","username_max_length":32,"reserved_usernames":["admin","root","support"]}'
```