# 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`.

```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"
}
```

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

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