# Token de acceso a la API frontal

Los endpoints de cuenta de la API frontal (`/fapi/v1/me…`, `/fapi/v1/verifications…` y `/fapi/v1/organizations…`) aceptan dos tipos de autenticación:

- la cookie `__Host-idp_session` del usuario, en el host de inicio de sesión del entorno (las páginas de cuenta alojadas usan esta);
- un token de acceso a la API frontal, para una aplicación de primera parte que se ejecuta en otro origen (una aplicación de página única o una aplicación nativa).

## Obtener el token

Solicite al endpoint de tokens de la API frontal como recurso (RFC 8707), en un intercambio de código de autorización o en una renovación:

```http
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
DPoP: <proof>

grant_type=refresh_token&refresh_token=<refresh token>&client_id=app_01j9...&resource=https%3A%2F%2Facme.keenauth.app%2Ffapi
```

El valor es el emisor del entorno seguido de `/fapi`. La solicitud se acepta solo cuando:

- la aplicación es una aplicación de primera parte activa (en caso contrario, `invalid_target`);
- la solicitud incluye una prueba DPoP (en caso contrario, `invalid_dpop_proof`);
- la concesión pertenece a una sesión de inicio de sesión, y en una renovación el refresh token está vinculado a DPoP (en caso contrario, `invalid_target`).

Solo cambia el token de acceso. Su audiencia es `<issuer>/fapi`, incluye solo los scopes OpenID de la concesión (`openid`, `profile`, `email`, `phone`, `offline_access`), tiene la misma duración que un token de userinfo y está vinculado a la clave de la prueba. La concesión en sí, su refresh token y sus scopes permanecen como están; una renovación rota el refresh token como de costumbre.

## Llamar a los endpoints de cuenta

Envíe el token con el esquema DPoP y una nueva prueba para cada solicitud (RFC 9449):

```http
GET /fapi/v1/me/sessions
Idp-Client: <SDK identifier>
Authorization: DPoP <access token>
DPoP: <proof with htm, htu, iat, jti, ath>
```

- `htu` es `https://<sign-in host>` más la ruta, sin la query. `ath` es el SHA-256 en base64url del token de acceso.
- No se lee ninguna cookie. La solicitud actúa sobre la sesión para la que se emitió el token; si esa sesión terminó, el token deja de funcionar.
- Una solicitud de navegador desde otro origen debe provenir de uno de los orígenes web permitidos de la aplicación. Las solicitudes entre orígenes nunca llevan credenciales.
- Un cambio sensible sigue requiriendo un inicio de sesión reciente. La respuesta `401 step_up_required` incluye entonces `WWW-Authenticate: DPoP error="insufficient_user_authentication", …, max_age=300`.

## Errores

| Estado | Código | Cuándo |
| --- | --- | --- |
| 400 | `malformed_request` | Hay más de un encabezado `Authorization`, o uno que no es `DPoP <token>`. |
| 401 | `unauthenticated` | El token no es válido, ha expirado o ha sido revocado, tiene otra audiencia, no está vinculado a DPoP, o su sesión o aplicación ya no están activas. |
| 401 | `invalid_dpop_proof` | La prueba no es válida o fue firmada con otra clave. |
| 401 | `use_dpop_nonce` | Envíe una nueva prueba con el nonce del encabezado `DPoP-Nonce`. |
| 403 | `origin_not_allowed` | El origen de la página no es uno de los orígenes web permitidos de la aplicación. |

Cada `401` incluye un desafío `WWW-Authenticate: DPoP …`.