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).

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

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