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.

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

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