Mettre à jour les paramètres d'identité

PATCH /v1/identity-settings · permission identity-settings:write

Met à jour les paramètres de nom d'utilisateur de l'environnement avec un correctif de fusion JSON (application/merge-patch+json, RFC 7396). If-Match est obligatoire : absent, 428 ; version obsolète, 412. Si les paramètres n'ont jamais été écrits, la version est "0" et la première écriture crée la ligne. Un correctif qui ne change rien n'écrit rien et conserve la version.

Requête

Champ	Type	Obligatoire	Description
`If-Match`	header	oui	L'`ETag` des paramètres tel qu'il a été lu en dernier (`"0"` s'ils n'ont jamais été écrits). Manquant : `428` ; obsolète : `412`.
`username_identifier`	string	non	`required`, `optional` ou `off`. Ne peut pas être `null`.
`username_min_length`	integer	non	3 à 64, pas supérieur à `username_max_length`. Ne peut pas être `null`.
`username_max_length`	integer	non	3 à 64, pas inférieur à `username_min_length`. Ne peut pas être `null`.
`reserved_usernames`	string[] \| null	non	1000 noms au plus ; remplace toute la liste (RFC 7396 ne fusionne pas les tableaux). `null` ou `[]` la vide. Chaque entrée est normalisée, les doublons sont supprimés et la liste est stockée triée.
`verification_policy`	string	non	`before_sign_in` (par défaut) ou `after_sign_in`. `after_sign_in` arrête le nettoyage des comptes non vérifiés. Ne peut pas être `null`.
`unverified_account_ttl_days`	integer	non	1-30 (7 par défaut) : nombre de jours pendant lesquels une inscription non vérifiée est conservée dans un environnement `before_sign_in` avant d'être supprimée. Ne peut pas être `null`.

Les paramètres de nom d'utilisateur ne s'appliquent qu'aux écritures suivantes ; ils ne modifient jamais les utilisateurs existants. Les paramètres de vérification agissent aussi sur les inscriptions existantes (voir ci-dessous).

Règles d'application

off (par défaut) : une requête qui écrit un nom d'utilisateur (POST /v1/users, PATCH /v1/users/{id}) échoue avec 422 et le code identifier_type_disabled (pointeur /username). Effacer un nom d'utilisateur existant reste autorisé, et un correctif d'utilisateur qui ne touche pas au nom d'utilisateur n'est pas revérifié. La connexion ne résout pas les comptes par nom d'utilisateur.
optional : un nom d'utilisateur peut être défini. required : créer un utilisateur via l'API de gestion sans nom d'utilisateur échoue avec 422 (required), et un correctif de gestion ne peut pas l'effacer. Demander le nom d'utilisateur dans le formulaire d'inscription relève de la connexion hébergée ; la création sociale et juste-à-temps (JIT) ne le demande jamais.
Longueur : un nom d'utilisateur plus court que username_min_length ou plus long que username_max_length échoue avec 422 (invalid).
Noms réservés : un nom d'utilisateur dont la forme normalisée figure dans reserved_usernames échoue avec 422 et le code username_reserved. Une entrée de liste invalide échoue avec 422 et le pointeur /reserved_usernames/<i>.
Les utilisateurs existants ne sont pas modifiés quand le paramètre change ; les règles ne s'appliquent qu'aux écritures suivantes.

Nettoyage des comptes non vérifiés

verification_policy et unverified_account_ttl_days pilotent le nettoyage automatique des inscriptions jamais vérifiées. Le nettoyage ne s'exécute que si l'adresse e-mail (ou le numéro de téléphone) est un identifiant obligatoire, ce qui est le cas par défaut pour l'e-mail.

before_sign_in (par défaut) : un utilisateur créé par inscription ne peut pas recevoir de jetons avant d'avoir vérifié l'identifiant obligatoire. Un utilisateur inscrit qui, unverified_account_ttl_days jours (1-30, 7 par défaut) après son inscription, n'a toujours aucune adresse e-mail ni aucun numéro de téléphone vérifié, n'a jamais reçu de jeton et n'a aucune identité sociale ou d'entreprise (SAML/OIDC) est supprimé définitivement. Le nettoyage s'exécute périodiquement (toutes les heures par défaut).
after_sign_in : les utilisateurs reçoivent des jetons avant de vérifier (email_verified: false) ; le nettoyage ne s'exécute pas et aucun utilisateur n'est supprimé.
Jamais supprimés : les utilisateurs créés par l'API de gestion, l'import, SCIM, une invitation ou la fédération juste-à-temps, les utilisateurs bloqués et ceux dont la suppression a déjà commencé. Seules les inscriptions créées après le démarrage du nettoyage dans l'environnement sont concernées.
La suppression est irréversible : l'utilisateur est supprimé définitivement, une pierre tombale de motif unverified_expired est conservée et l'événement user.deleted est publié.
Un changement de politique ou de durée prend effet à l'exécution suivante. Réduire unverified_account_ttl_days rend immédiatement éligibles les inscriptions non vérifiées plus anciennes ; repasser de after_sign_in à before_sign_in supprime les inscriptions non vérifiées expirées à l'exécution suivante.

Réponse

200 OK avec les paramètres mis à jour et le nouvel 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"
}

Erreurs

HTTP	code	Quand
400	`unknown_field`	Le correctif contient un champ inconnu ou en lecture seule, ou n'est pas un objet JSON (`malformed_request`).
412	`precondition_failed`	`If-Match` ne correspond pas à la version actuelle.
415	`unsupported_media_type`	Le type de contenu n'est pas `application/merge-patch+json`.
422	`validation_failed`	Une valeur est invalide, `min` dépasse `max`, ou un champ qui ne peut pas être `null` a été mis à `null` (`code: invalid`).
428	`precondition_required`	L'en-tête `If-Match` est manquant.
401	`unauthenticated`	L'authentification est manquante, invalide ou révoquée.
403	`insufficient_permissions`	L'authentification manque la permission requise.
429	`rate_limited`	La limite de débit a été dépassée ; réessayez après la période `Retry-After`.
503	`service_unavailable`	Une dépendance est temporairement indisponible ; réessayez après la période `Retry-After`.

Exemple

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