# 프런트 API 액세스 토큰

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

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

## 토큰 발급받기

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

```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
```

값은 환경의 발급자(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):

```http
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 …` 질의가 포함됩니다.