# Establecer una dirección de correo electrónico como principal

`POST /fapi/v1/me/emails/{email_id}:set-primary` · llamado desde el host de inicio de sesión del entorno

Hace que una de las direcciones de correo electrónico verificadas del usuario autenticado sea la principal. Una dirección no verificada no puede convertirse en principal; verifíquela primero. Tras el cambio, la dirección principal anterior y las demás direcciones verificadas del usuario reciben una notificación de seguridad con un enlace de "no fui yo" que abre la recuperación de la cuenta. Si la dirección ya es la principal, la respuesta sigue siendo `204` y no se cambia ni se envía nada. Requiere la cookie `__Host-idp_session` del usuario autenticado; si la cookie falta, ha expirado o ha sido revocada, devuelve `401 unauthenticated`. Una aplicación de origen propio 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](/docs/api/fapi/front-api-token)).

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://<host de inicio de sesión>`. |

`email_id`: el identificador de la dirección de correo electrónico, el mismo valor que usan los endpoints `/v1/users/{user_id}/emails` de la API de gestión (UUID en minúsculas).

Sin cuerpo.

## Respuesta

`204 No Content`.

## Errores

| Estado | Código | Cuándo |
| --- | --- | --- |
| 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 corresponde, `acr_values`) en el encabezado `WWW-Authenticate`. |
| 403 | `origin_not_allowed` | `Origin` falta o es incorrecto. |
| 404 | `not_found` | No existe esta dirección de correo electrónico para este usuario. |
| 409 | `primary_requires_verified` | La dirección de correo electrónico no está verificada. |

## Ejemplo

```bash
curl -X POST https://example.keenauth.app/fapi/v1/me/emails/0190a5c4-1b2c-7d3e-8f40-516273849abc:set-primary \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -b cookies.txt
```

## Datos personales

Este endpoint contiene datos personales: perfil del usuario final. [Datos personales en las API de KeenAuth](/docs/policies/personal-data) 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.