# Front API erişim belirteci

Front API'nin hesap uç noktaları (`/fapi/v1/me…`, `/fapi/v1/verifications…` ve `/fapi/v1/organizations…`) iki tür kimlik doğrulamayı kabul eder:

- kullanıcının `__Host-idp_session` çerezi, ortamın giriş ana makinesinde (barındırılan hesap sayfaları bunu kullanır);
- başka bir kökende çalışan birinci taraf bir uygulama (tek sayfalık uygulama veya yerel uygulama) için bir Front API erişim belirteci.

## Belirteci alma

Yetkilendirme kodu değişiminde veya yenilemede, Front API için belirteç uç noktasından kaynak olarak (RFC 8707) talepte bulunun:

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

Değer, ortamın issuer değerine `/fapi` eklenerek oluşturulur. İstek yalnızca şu durumlarda kabul edilir:

- uygulama etkin bir birinci taraf uygulamadır (aksi halde `invalid_target`);
- istek bir DPoP kanıtı taşır (aksi halde `invalid_dpop_proof`);
- yetki bir oturum açma oturumuna aittir ve yenilemede yenileme belirteci DPoP'a bağlıdır (aksi halde `invalid_target`).

Yalnızca erişim belirteci değişir. Hedef kitlesi `<issuer>/fapi` olur, yalnızca yetkinin OpenID kapsamlarını (`openid`, `profile`, `email`, `phone`, `offline_access`) taşır, bir userinfo belirteci kadar geçerli kalır ve kanıtın anahtarına bağlanır. Yetkinin kendisi, yenileme belirteci ve kapsamları olduğu gibi kalır; yenileme, yenileme belirtecini her zamanki gibi döndürür.

## Hesap uç noktalarını çağırma

Belirteci DPoP şemasıyla gönderin ve her istek için yeni bir kanıt kullanın (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`, sorgu dizesi olmadan `https://<giriş ana makinesi>` ile yoldan oluşur. `ath`, erişim belirtecinin base64url SHA-256 değeridir.
- Çerez okunmaz. İstek, belirtecin verildiği oturum üzerinde işlem yapar; o oturum sona ererse belirteç çalışmayı durdurur.
- Başka bir kökenden gelen tarayıcı isteği, uygulamanın izin verilen web kökenlerinden birinden gelmelidir. Kökenler arası istekler hiçbir zaman kimlik bilgisi taşımaz.
- Hassas bir değişiklik için hâlâ yakın tarihli bir giriş gerekir. Bu durumda `401 step_up_required` yanıtı `WWW-Authenticate: DPoP error="insufficient_user_authentication", …, max_age=300` başlığını taşır.

## Hatalar

| Durum | Kod | Ne zaman |
| --- | --- | --- |
| 400 | `malformed_request` | Birden fazla `Authorization` başlığı var veya başlık `DPoP <token>` biçiminde değil. |
| 401 | `unauthenticated` | Belirteç geçersiz, süresi dolmuş veya iptal edilmiş; farklı bir hedef kitleye sahip; DPoP'a bağlı değil; ya da oturumu veya uygulaması artık etkin değil. |
| 401 | `invalid_dpop_proof` | Kanıt geçersiz veya başka bir anahtarla imzalanmış. |
| 401 | `use_dpop_nonce` | `DPoP-Nonce` başlığındaki nonce ile yeni bir kanıt gönderin. |
| 403 | `origin_not_allowed` | Sayfa kökeni, uygulamanın izin verilen web kökenlerinden biri değil. |

Her `401` yanıtı bir `WWW-Authenticate: DPoP …` sorgusu taşır.