Jeton d'accès à l'API front

Les points de terminaison de compte de l'API front (/fapi/v1/me…, /fapi/v1/verifications… et /fapi/v1/organizations…) acceptent deux types d'authentification :

le cookie __Host-idp_session de l'utilisateur, sur l'hôte de connexion de l'environnement (les pages de compte hébergées utilisent ce mécanisme) ;
un jeton d'accès à l'API front, pour une application de première partie qui s'exécute sur une autre origine (une application monopage ou une application native).

Obtenir le jeton

Demandez au point de terminaison de jetons l'API front en tant que ressource (RFC 8707), lors d'un échange de code d'autorisation ou d'un renouvellement :

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

La valeur correspond à l'émetteur de l'environnement suivi de /fapi. La requête n'est acceptée que lorsque :

l'application est une application de première partie active (sinon invalid_target) ;
la requête contient une preuve DPoP (sinon invalid_dpop_proof) ;
l'octroi appartient à une session de connexion, et lors d'un renouvellement le jeton de renouvellement est lié à DPoP (sinon invalid_target).

Seul le jeton d'accès change. Son audience est <issuer>/fapi, il ne porte que les autorisations OpenID de l'octroi (openid, profile, email, phone, offline_access), il a la même durée de vie qu'un jeton userinfo, et il est lié à la clé de la preuve. L'octroi lui-même, son jeton de renouvellement et ses autorisations restent inchangés ; un renouvellement fait tourner le jeton de renouvellement comme d'habitude.

Appeler les points de terminaison de compte

Envoyez le jeton avec le schéma DPoP et une nouvelle preuve pour chaque requête (RFC 9449) :

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

htu correspond à https://<hôte de connexion> suivi du chemin, sans la requête. ath est le SHA-256 du jeton d'accès, encodé en base64url.
Aucun cookie n'est lu. La requête agit sur la session pour laquelle le jeton a été émis ; si cette session prend fin, le jeton cesse de fonctionner.
Une requête de navigateur provenant d'une autre origine doit venir de l'une des origines web autorisées de l'application. Les requêtes inter-origines ne transportent jamais d'identifiants.
Une modification sensible exige toujours une connexion récente. La réponse 401 step_up_required contient alors WWW-Authenticate: DPoP error="insufficient_user_authentication", …, max_age=300.

Erreurs

Statut	Code	Quand
400	`malformed_request`	Plus d'un en-tête `Authorization`, ou un en-tête qui n'est pas `DPoP <token>`.
401	`unauthenticated`	Le jeton est invalide, expiré ou révoqué, a une autre audience, n'est pas lié à DPoP, ou sa session ou son application n'est plus active.
401	`invalid_dpop_proof`	La preuve est invalide ou a été signée avec une autre clé.
401	`use_dpop_nonce`	Envoyez une nouvelle preuve avec le nonce de l'en-tête `DPoP-Nonce`.
403	`origin_not_allowed`	L'origine de la page ne fait pas partie des origines web autorisées de l'application.

Chaque 401 contient un challenge WWW-Authenticate: DPoP ….