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:

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

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