# Oturum açma adımını çalıştırma

`POST /fapi/v1/transactions/current/steps/{step}` · ortamın oturum açma sunucusundan çağrılır

Geçerli işlemin bir adımını çalıştırır. Bu sürüm `identifier` ve `password` adımlarını kabul eder. Başarısız her kimlik bilgisi adımı aynı `401 invalid_credentials` yanıtını döndürür; böylece yanıt bir hesabın var olup olmadığını asla ortaya koymaz. Parola adımı işlemi tamamladığında oturum çerezleri `__Host-idp_session` (gerektiğinde `__Host-idp_device` ile birlikte) ayarlanır ve işlem çerezi kaldırılır.

## İstek

Üstbilgiler:

| Üstbilgi | Zorunlu | Açıklama |
| --- | --- | --- |
| `Idp-Client` | evet | SDK tanımlayıcısı. |
| `Origin` | evet | Tam olarak `https://<sign-in host>` olmalıdır. |
| `Idp-Csrf-Token` | evet | İşlem nesnesindeki `csrf_token`. |

Yol: `step`, adımın adı (`identifier`, `password`, `sso_start`).

`otp_send` adımında `next_steps[].methods`, etkin politikanın izin verdiği parolasız yöntemleri listeler (`email_otp`, `magic_link`); istemci yalnızca bunları sunar.

Gövde (alanlar adıma göre değişir; `next_steps[].fields` bunları listeler):

| Alan | Tür | Açıklama |
| --- | --- | --- |
| `identifier` | string | E-posta adresi, telefon numarası veya kullanıcı adı (`identifier` adımı), en fazla 320 karakter. |
| `password` | string | Parola (`password` adımı), en fazla 128 karakter. |
| `connection_id` | string | Bir `sso_connections[].connection_id` değeri (`sso_start` adımı). |

## Yanıt

Adımdan sonraki işlem ile `200 OK` döndürülür. `completed` işleminin `csrf_token` yoktur.

Ortam ikinci bir faktör gerektiriyor ve kullanıcının henüz hiç faktörü yoksa, ortamın `mfa.enrollment_grace_days` süresi içindeki kullanıcı yine de oturum açar ve `completed` yanıtı şunu içerir: `mfa_enrollment` `required_by` (RFC 3339, sürenin bitiş zamanı, sunucu tarafından hesaplanır) ve `methods` (`webauthn`, `totp`: kullanıcının şimdi kaydedebileceği faktörler, ekrandaki sırayla). Tarihi gösterin ve kullanıcının devam etmesine izin verin; kayıt, hesap ayarlarına eklenir. Alan; süre tanınmadığında, kullanıcı politikayı zaten karşıladığında veya kayıt hemen zorunlu olduğunda bulunmaz. Bir uygulamanın `min_acr` ve istenen `acr_values` hiçbir zaman süre tanınması nedeniyle ertelenmez.

## Kurumsal SSO (ana bölge keşfi)

`identifier` adımı, alan adı bir kurumsal bağlantıya ait olan bir e-posta adresi aldığında oturum açma o bağlantıyla devam eder. Keşif için yalnızca `@` sonrasındaki kısım kullanılır.

- Tek bağlantı: İşlem `federated_redirect` durumuna geçer ve yanıt, kimlik sağlayıcının başlangıç adresi olan `redirect_url` alanını içerir. Üst düzey pencereyi oraya yönlendirin. Adres tek kullanımlık bir belirteç içerir: onu saklamayın ve günlüğe yazmayın.
- Birden fazla bağlantı: İşlem `identifier_pending` durumunda kalır ve yanıt `sso_connections` listesini içerir (`connection_id`, `display_name`, `protocol`). `display_name` alanını metin olarak gösterin ve kullanıcının seçimini `sso_start` adımıyla gönderin (`identifier` ve `connection_id`). Alan adı için sunulmayan bir bağlantı `422 validation_failed` döndürür.
- Bağlantı yok veya keşif geçici olarak kullanılamıyorsa normal oturum açma devam eder; böylece bir kesinti diğer oturum açma yöntemlerini engellemez. `sso_start` açık bir seçimdir ve bunun yerine `503 temporarily_unavailable` döndürür.

Oturum açma isteği SSO gerektiren bir kuruluşu belirttiğinde işlem yalnızca o kuruluşun bağlantılarını sunar: parola ve e-posta kodu adımları sunulmaz; Passkey yalnızca kuruluşun acil durum (break-glass) hesapları varsa kullanılabilir kalır. İşlemi oluşturmak, tek olan bağlantıyı zaten başlatır (`federated_redirect` ile `redirect_url`) ya da `sso_connections` içinde birden fazlasını listeler; seçimi yalnızca `sso_start` ve `connection_id` ile gönderin, `identifier` burada isteğe bağlıdır. Bu gereksinim altında keşif başka yöntemlere geri dönmez: kurumsal oturum açmaya ulaşılamadığında adım `503 temporarily_unavailable` döndürür. E-posta alan adı, doğrulanmış alan adları için SSO isteyen bir kuruluşa aitse aynı kural geçerlidir.

Kimlik sağlayıcıdan sonra tarayıcı, oturum açma sunucusundaki `/u/sso/complete` adresine döner; barındırılan sayfa oturum açmayı tamamlar.

## Kurumsal oturum açmayı mevcut hesapla bağlama

Kurumsal bir bağlantı e-posta adreslerini doğrulamıyorsa ve bildirdiği adres ortamın bir hesabında zaten doğrulanmışsa, kurumsal oturum açma bir oturum başlatmaz. Tarayıcı, nesnesi `account_link` taşıyan yeni bir işlemle barındırılan oturum açma sayfasına döner: `connection_name` ve bağlantı bir kuruluşa aitse `organization_name`. Kullanıcıya zaten bir hesabı olduğunu ve bağlantıyı bağlamak için o hesaba giriş yapması gerektiğini söyleyin; hesabı asla adıyla belirtmeyin. Bu işlemde `sso_start` ve `magic_link` sunulmaz ve `identifier` adımı kurumsal bir bağlantıya yönlendirmez.

Kullanıcı mevcut hesabına kendi yöntemleriyle giriş yapar; ikinci faktörü kayıtlı bir kullanıcıdan bu faktör istenir. İşlemi tamamlayan adım bir oturum açmaz: bağlantı hesaba bağlanır ve yanıt, aynı bağlantı için `redirect_url` bulunan ve `federated_redirect` durumunda yeni bir işlemdir. Üst düzey pencereyi oraya yönlendirin; kurumsal oturum açma artık olağan şekilde tamamlanır. Kurumsal oturum açma başlatılamazsa yeni işlem `identifier_pending` durumunda olur ve ardından olağan bir oturum açma gelir.

Başka bir hesapla, kayıtlı ikinci faktör olmadan veya bağlantı isteğinden daha eski bir oturum açmayla tamamlamak hiçbir şeyi bağlamaz ve oturum açmaz: `409 transaction_state_conflict`. Süresi dolmuş (10 dakika) veya zaten kullanılmış bir bağlantı isteği `410 transaction_expired` döndürür. Bir bağlantı isteği, sonucu ne olursa olsun bir kez kullanılır. Reddetmek için `POST /fapi/v1/transactions/current:cancel` çağrısını yapın.

## Kuruluş politikası

Yetkilendirme isteği bir kuruluşa bağlıysa kuruluşun oturum açma politikası, birinci faktörden sonra ve oturum açılmadan hemen önce yeniden denetlenir:

- İstemcinin IP adresi kuruluşun izin listesinde değilse: `403 ip_not_allowed`.
- İşlemin faktörleri kuruluş politikasını karşılamıyorsa (kuruluşun izin vermediği bir yöntem, eksik bir faktör ya da kuruluşun AAGUID izin listesi dışında bir güvenlik anahtarı veya Passkey): `403 no_allowed_method`.
- Kuruluşun politikası okunamıyorsa: `503 temporarily_unavailable`. Oturum açma kapalı kalır ve politika olmadan asla devam etmez.

Hiçbir oturum açılmaz. İşlem tamamlanırken yapılan bir red, işlem çerezini kaldırır; birinci faktörden sonraki `503` işlemi olduğu yerde bırakır ve adım yeniden denenebilir. Hata gövdesi hiçbir zaman kuruluşu, kullanıcıyı veya IP adresini adıyla belirtmez.

## DPoP'ye bağlı başsız işlemler

`DPoP` üstbilgisiyle başlatılan bir işlem için, `Idp-Csrf-Token` yerine aynı anahtardan yeni bir kanıt gönderin (`htm` `POST`, `htu` adım URL'si); çerez kullanılmaz. İşlemi tamamlayan adım `authorization_response` değerini yalnızca bir kez döndürür:

```json
{
  "state": "completed",
  "authorization_response": { "code": "<code>", "state": "<your state>", "iss": "https://example.keenauth.app" },
  "next_steps": [],
  "schema_version": 1,
  "expires_at": "2026-11-02T10:15:00Z"
}
```

`state` ile `iss` değerlerinin eşleştiğini doğrulayın, ardından kodu `/oauth2/token` adresinde `code_verifier` ve aynı anahtardan bir DPoP kanıtıyla değiştirin. Başka bir anahtardan gelen kanıt `invalid_grant` döndürür. Yetkilendirme isteği bir kodla sonuçlanamazsa (onay, yasal şartlar, bir kuruluş seçimi ya da yeni bir oturum açma gerekiyorsa veya erişim reddedilmişse), adım `403 authorization_failed` döndürür ve `error` üyesi OAuth hata kodunu taşır; hiçbir kod verilmez.

## Hatalar

| Durum | Kod | Ne zaman |
| --- | --- | --- |
| 401 | `invalid_credentials` | Tanımlayıcı veya parola kabul edilmedi. |
| 403 | `origin_not_allowed` | `Origin` veya `Idp-Csrf-Token` eksik ya da hatalı. |
| 403 | `ip_not_allowed` | İstemcinin IP adresi kuruluşun izin listesinde değil. |
| 403 | `no_allowed_method` | Oturum açma kuruluş politikasını karşılamıyor. |
| 403 | `test_feature_not_in_production` | `otp_verify` veya `email_2fa`, üretim ortamında sabit test kodu `424242` değerini aldı. Deneme, yanlış kod gibi sayılır. |
| 404 | `not_found` | Adım adı bilinen bir adım değil. |
| 409 | `transaction_state_conflict` | Adım geçerli durumda kullanılamıyor. |
| 409 | `session_limit_reached` | Kullanıcı oturum sınırına ulaştı ve yeni oturumlar reddediliyor. |
| 410 | `transaction_expired` | İşlem sona erdi. |
| 422 | `validation_failed` | Bir alan eksik veya geçersiz. |
| 503 | `temporarily_unavailable` | `sso_start` kurumsal oturum açmaya ulaşamadı veya kuruluşun politikası okunamadı; yeniden deneyin. |
| 401 | `invalid_dpop_proof` | `DPoP` kanıtı eksik, geçersiz veya yeniden kullanılmış. |
| 403 | `authorization_failed` | DPoP'ye bağlı işlem tamamlandı, ancak yetkilendirme isteği kod olmadan sonuçlandı. |

## Örnek

```bash
curl -X POST https://example.keenauth.app/fapi/v1/transactions/current/steps/identifier \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Idp-Csrf-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"identifier":"jane@example.com"}'
```

## Kişisel veriler

Bu uç nokta kişisel veri içerir: son kullanıcı profili ve kimlik bilgileri. [KeenAuth API'lerinde kişisel veriler](/docs/policies/personal-data) neyin saklandığını, ne kadar süre tutulduğunu ve nasıl silindiğini açıklar. Hiçbir alanda özel nitelikli kişisel verileri (sağlık, biyometrik veriler, din, siyasi görüşler, cinsel yönelim) göndermeyin.