Añadir una dirección de correo electrónico
POST /fapi/v1/me/emails · llamado desde el host de inicio de sesión del entorno
Añade una dirección de correo electrónico al usuario autenticado como dirección no verificada y no principal, y envía a ella un enlace de verificación. La dirección pasa a estar disponible cuando el usuario abre el enlace. Toda solicitud aceptada responde 202 sin cuerpo, incluso cuando la dirección ya pertenece a este usuario; la respuesta nunca muestra si la dirección está en uso en otra cuenta. Un usuario tiene como máximo 10 direcciones, incluida la principal. Requiere la cookie __Host-idp_session del usuario autenticado; si la cookie falta, ha caducado o ha sido revocada, devuelve 401 unauthenticated. Una aplicación propia en otro origen puede enviar en su lugar su token de acceso a la API frontal (Authorization: DPoP <token> con una prueba DPoP; consulte Token de acceso a la API frontal).
La sesión debe haberse verificado en los últimos 5 minutos. Si el usuario tiene un segundo factor, la sesión también debe haberse abierto con un segundo factor (urn:idp:acr:mfa).
Solicitud
Encabezados:
| Encabezado | Obligatorio | Descripción |
|---|---|---|
Idp-Client |
sí | Identificador del SDK. |
Origin |
sí | Debe ser exactamente https://<sign-in host>. |
Content-Type |
sí | application/json. |
Cuerpo:
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
email |
string | sí | La dirección que se va a añadir (como máximo 320 caracteres). |
Respuesta
202 Accepted, sin cuerpo.
Errores
| Estado | Código | Cuándo |
|---|---|---|
| 400 | malformed_request |
El cuerpo no es JSON válido. |
| 400 | unknown_field |
El cuerpo tiene un campo distinto de email. |
| 401 | unauthenticated |
No hay una cookie de sesión válida. |
| 401 | step_up_required |
La sesión no se verificó en los últimos 5 minutos o se requiere un segundo factor; vuelva a verificar con max_age=300 (y, si procede, acr_values) en el encabezado WWW-Authenticate. |
| 403 | origin_not_allowed |
Origin falta o es incorrecto. |
| 409 | email_limit_reached |
El usuario ya tiene 10 direcciones de correo electrónico. |
| 413 | payload_too_large |
El cuerpo es demasiado grande. |
| 415 | unsupported_media_type |
Content-Type no es application/json. |
| 422 | validation_failed |
Falta email. |
| 422 | email_invalid |
email no es una dirección de correo electrónico válida. |
| 422 | email_domain_not_allowed |
El entorno no permite direcciones de este dominio. |
| 429 | verification_rate_limited |
Se enviaron demasiados mensajes de verificación recientemente; inténtelo más tarde. |
Ejemplo
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"}'
Datos personales
Este endpoint contiene datos personales: perfil del usuario final. Datos personales en las API de KeenAuth describe qué se almacena, cuánto tiempo se conserva y cómo se elimina. No envíe categorías especiales de datos personales (salud, datos biométricos, religión, opiniones políticas, orientación sexual) en ningún campo.