프런트 API 액세스 토큰

프런트 API의 계정 엔드포인트(/fapi/v1/me…, /fapi/v1/verifications… 및 /fapi/v1/organizations…)는 다음 두 가지 인증 방식을 허용합니다:

환경의 로그인 호스트에서 사용하는 사용자의 __Host-idp_session 쿠키(호스팅된 계정 페이지가 이 방식을 사용합니다);
다른 출처에서 실행되는 자사 애플리케이션(단일 페이지 앱 또는 네이티브 앱)용 프런트 API 액세스 토큰.

토큰 발급받기

인증 코드 교환 또는 갱신 시, 리소스(RFC 8707)로 프런트 API를 지정하여 토큰 엔드포인트에 요청하십시오:

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

값은 환경의 발급자(issuer) 뒤에 /fapi를 붙인 것입니다. 요청은 다음 조건을 모두 충족할 때만 허용됩니다:

활성 상태의 자사 애플리케이션이어야 합니다(그렇지 않으면 invalid_target);
요청에 DPoP 증명이 포함되어 있어야 합니다(그렇지 않으면 invalid_dpop_proof);
grant가 로그인 세션에 속해야 하며, 갱신의 경우 갱신 토큰이 DPoP에 바인딩되어 있어야 합니다(그렇지 않으면 invalid_target).

액세스 토큰만 변경됩니다. 대상(audience)은 <issuer>/fapi이며, grant의 OpenID 스코프(openid, profile, email, phone, offline_access)만 포함합니다. 유효 기간은 userinfo 토큰과 같고, 증명의 키에 바인딩됩니다. grant 자체, 그 갱신 토큰 및 스코프는 그대로 유지되며, 갱신 시 갱신 토큰은 평소와 같이 교체됩니다.

계정 엔드포인트 호출하기

DPoP 방식으로 토큰을 전송하고, 요청마다 새 증명을 함께 보내십시오(RFC 9449):

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

htu는 쿼리를 제외한 https://<sign-in host>와 경로입니다. ath는 액세스 토큰의 base64url 인코딩된 SHA-256 값입니다.
쿠키는 읽지 않습니다. 요청은 토큰이 발급된 세션을 기준으로 처리되며, 해당 세션이 종료되면 토큰은 더 이상 작동하지 않습니다.
다른 출처에서 보내는 브라우저 요청은 애플리케이션의 허용된 웹 출처 중 하나에서 와야 합니다. 교차 출처 요청에는 자격 증명이 포함되지 않습니다.
민감한 변경에는 여전히 최근 로그인이 필요합니다. 이때 401 step_up_required 응답에는 WWW-Authenticate: DPoP error="insufficient_user_authentication", …, max_age=300이 포함됩니다.

오류

상태	코드	발생 조건
400	`malformed_request`	`Authorization` 헤더가 두 개 이상이거나, `DPoP <token>` 형식이 아닌 경우.
401	`unauthenticated`	토큰이 유효하지 않거나, 만료 또는 취소되었거나, 대상이 다르거나, DPoP에 바인딩되지 않았거나, 세션 또는 애플리케이션이 더 이상 활성 상태가 아닌 경우.
401	`invalid_dpop_proof`	증명이 유효하지 않거나 다른 키로 서명된 경우.
401	`use_dpop_nonce`	`DPoP-Nonce` 헤더의 nonce를 사용하여 새 증명을 보내십시오.
403	`origin_not_allowed`	페이지 출처가 애플리케이션의 허용된 웹 출처 중 하나가 아닌 경우.

각 401 응답에는 WWW-Authenticate: DPoP … 질의가 포함됩니다.