# Définir une adresse e-mail vérifiée comme adresse principale de l'utilisateur

`POST /v1/users/{user_id}/emails/{email_id}:set-primary` · autorisation `users:write`

Définit une adresse vérifiée comme adresse principale de l'utilisateur ; l'ancienne adresse principale reste une adresse secondaire. Une adresse non vérifiée ne peut pas devenir principale. Si l'adresse est déjà principale, rien n'est écrit et `200` est renvoyé. La modification est écrite dans le journal d'audit de gestion sous `user.primary_email_changed`, avec la clé API comme acteur, et émet `user.updated`.

## Requête

| Paramètre | Dans | Obligatoire | Description |
|---|---|---|---|
| `user_id` | path | oui | Identifiant de l'utilisateur, préfixé `usr_`. |
| `email_id` | path | oui | Identifiant de la ligne d'adresse e-mail (UUID interne, en minuscules, avec tirets), tel que renvoyé par `GET /v1/users/{user_id}/emails`. |

La requête ne prend pas de corps (un corps vide ou `{}` est accepté).

## Réponse

`200 OK` avec la ligne d'adresse e-mail mise à jour. Sans l'autorisation `users:read_pii`, l'adresse est masquée (`a***@e***.com`).

```json
{
  "id": "0191f0a0-3333-7444-8555-666666666666",
  "email": "ada@example.com",
  "verified": true,
  "primary": true,
  "created_at": "2026-01-15T09:30:00Z"
}
```

## Erreurs

Chaque erreur est un corps `application/problem+json` avec un `code` stable.

| HTTP | `code` | Quand |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Le corps n'est pas un JSON valide, ou n'est ni vide ni `{}`. |
| 409 | `primary_requires_verified` | L'adresse n'est pas vérifiée. |
| 404 | `not_found` | L'utilisateur ou la ligne d'adresse e-mail n'existe pas dans cet environnement, l'adresse n'appartient pas à cet utilisateur, ou un identifiant est mal formé. |
| 401 | `unauthenticated` | La clé API est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé ne dispose pas de l'autorisation `users:write`. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; respectez `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez plus tard. |

## Exemple

```bash
curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/emails/0191f0a0-3333-7444-8555-666666666666:set-primary \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

## Données personnelles

Cet endpoint traite des données personnelles : profil de l'utilisateur final. [Données personnelles dans les API KeenAuth](/docs/policies/personal-data) décrit ce qui est stocké, la durée de conservation et la manière dont elles sont supprimées. N'envoyez aucune catégorie particulière de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.