Ajouter une adresse e-mail
POST /fapi/v1/me/emails · appelé depuis l'hôte de connexion de l'environnement
Ajoute une adresse e-mail à l'utilisateur authentifié, en tant qu'adresse non vérifiée et non principale, et envoie à cette adresse un lien de vérification. L'adresse devient utilisable une fois que l'utilisateur ouvre le lien. Chaque requête acceptée reçoit une réponse 202 sans corps, y compris lorsque l'adresse fait déjà partie des adresses de cet utilisateur ; la réponse ne révèle jamais si l'adresse est utilisée sur un autre compte. Un utilisateur détient au maximum 10 adresses, la principale comprise. Nécessite le cookie __Host-idp_session de l'utilisateur authentifié ; si le cookie est absent, expiré ou révoqué, renvoie 401 unauthenticated. Une application propriétaire sur une autre origine peut à la place envoyer son jeton d'accès à l'API frontale (Authorization: DPoP <token> avec une preuve DPoP ; voir Jeton d'accès à l'API frontale).
La session doit avoir été vérifiée au cours des 5 dernières minutes. Si l'utilisateur possède un second facteur, la session doit également avoir été ouverte avec un second facteur (urn:idp:acr:mfa).
Requête
En-têtes :
| En-tête | Obligatoire | Description |
|---|---|---|
Idp-Client |
oui | Identifiant du SDK. |
Origin |
oui | Doit être exactement https://<hôte de connexion>. |
Content-Type |
oui | application/json. |
Corps :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
email |
string | oui | L'adresse à ajouter (320 caractères au maximum). |
Réponse
202 Accepted, sans corps.
Erreurs
| Statut | Code | Quand |
|---|---|---|
| 400 | malformed_request |
Le corps n'est pas du JSON valide. |
| 400 | unknown_field |
Le corps contient un champ autre que email. |
| 401 | unauthenticated |
Aucun cookie de session valide. |
| 401 | step_up_required |
La session n'a pas été vérifiée au cours des 5 dernières minutes ou un second facteur est requis ; vérifiez à nouveau avec max_age=300 (et, le cas échéant, acr_values) dans l'en-tête WWW-Authenticate. |
| 403 | origin_not_allowed |
Origin est absent ou incorrect. |
| 409 | email_limit_reached |
L'utilisateur possède déjà 10 adresses e-mail. |
| 413 | payload_too_large |
Le corps est trop volumineux. |
| 415 | unsupported_media_type |
Content-Type n'est pas application/json. |
| 422 | validation_failed |
email est absent. |
| 422 | email_invalid |
email n'est pas une adresse e-mail valide. |
| 422 | email_domain_not_allowed |
L'environnement n'autorise pas les adresses de ce domaine. |
| 429 | verification_rate_limited |
Trop de messages de vérification ont été envoyés récemment ; réessayez plus tard. |
Exemple
curl -X POST https://example.keenauth.app/fapi/v1/me/emails \
-H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
-H "Origin: https://example.keenauth.app" \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"email": "ada@example.org"}'
Données personnelles
Ce point de terminaison traite des données personnelles : profil de l'utilisateur final. Données personnelles dans les API KeenAuth décrit ce qui est stocké, pendant combien de temps et comment 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.