# Giriş işlemi oluşturma `POST /fapi/v1/transactions` · ortamın giriş sunucusundan çağrılır Bir uygulama için giriş işlemi başlatır. Barındırılan giriş sayfası, kullanıcı arayüzü bileşenleri ve başsız istemciler, bu uç noktayı ortamın giriş sunucusunda (bir `keenauth.app` alt alan adı veya doğrulanmış özel alan adı) çağırır. Yanıt, `__Host-idp_ltx` işlem çerezini ayarlar (Secure, HttpOnly, SameSite=Lax, 15 dakika geçerlidir); sonraki adımlar bu çerezi kullanır. ## İstek Üstbilgiler: | Üstbilgi | Zorunlu | Açıklama | | --- | --- | --- | | `Idp-Client` | evet | SDK tanımlayıcısı, `/ (/)`. | | `Origin` | evet | Tam olarak `https://` olmalıdır. | Gövde: | Alan | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `client_id` | string | evet | Uygulamanın istemci kimliği. | | `redirect_uri` | string (URI) | evet | Uygulamanın kayıtlı yönlendirme URI'lerinden biri. | ## Yanıt İşlem nesnesiyle birlikte `201 Created`: ```json { "schema_version": 1, "state": "identifier_pending", "next_steps": [{ "step": "identifier", "fields": ["identifier"] }], "csrf_token": "", "expires_at": "2026-10-05T10:15:00Z" } ``` Bu işlemin durumunu değiştiren her istekte `csrf_token` değerini `Idp-Csrf-Token` üstbilgisiyle geri gönderin. Yetkilendirme isteği SSO gerektiren bir kuruluş belirtirse yanıt zaten `federated_redirect` olabilir ve `redirect_url` içerir (tek bağlantı: en üst düzey pencereyi oraya yönlendirin) ya da `sso_connections` içerebilir (birden fazla bağlantı: seçimi `sso_start` adımıyla gönderin). ## DPoP ile bağlanan başsız işlemler Kendi kaynağında çalışan birinci taraf bir SPA veya yerel uygulama, `DPoP` üstbilgisiyle başsız bir giriş başlatır (RFC 9449): istemcinin sakladığı bir anahtarla imzalanmış bir kanıt (tarayıcıda dışa aktarılamayan WebCrypto anahtarı, cihazda platform anahtar deposu), `htm` değeri `POST` ve `htu` değeri `https:///fapi/v1/transactions`. İşlem bu durumda çereze değil bu anahtara bağlanır: çerez ayarlanmaz ve nesnede `csrf_token` bulunmaz. İşlemin sonraki her isteği aynı anahtardan yeni bir kanıt gönderir. Yetkilendirme uç noktasının kurallarıyla kontrol edilen ek gövde alanları: | Alan | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `code_challenge` | string | evet | PKCE S256 challenge değeri (RFC 7636). | | `code_challenge_method` | string | evet | `S256`. | | `scope` | string | hayır | Boşlukla ayrılmış kapsamlar, örneğin `openid profile email offline_access`. | | `state` | string | hayır | Yetkilendirme koduyla birlikte döner. | | `nonce` | string | hayır | ID token `nonce` değeri. | | `organization` | string | hayır | Kuruluş kimliği veya adı. | | `ui_locales` | string | hayır | Tercih edilen diller. | | `resource` | string (URI) | hayır | Kaynak belirteci (RFC 8707). | `Origin` değeri giriş sunucusu veya uygulamanın izin verilen web kaynaklarından biri olabilir; yerel uygulama hiçbir değer göndermez. Bu tür işlemi yalnızca birinci taraf uygulamalar başlatabilir. Yetkilendirme uç noktasının reddettiği bir alan `422 validation_failed` döndürür ve `errors[].code` içinde OAuth hata kodunu verir. Sunucu `401 use_dpop_nonce` yanıtı verirse `DPoP-Nonce` yanıt üstbilgisinin değerini kullanarak yeni bir kanıt imzalayın ve isteği yeniden deneyin. Bu alanları `DPoP` üstbilgisi olmadan gönderirseniz `422 validation_failed` (`dpop_required`) döner. ## Kuruluşu değiştirme Oturum açmış kullanıcı için ön API erişim belirteci tutan bir uygulama (bkz. [Ön API erişim belirteci](/docs/api/fapi/front-api-token)), kullanıcıyı ekran göstermeden başka bir kuruluşa geçirebilir. Belirteci `Authorization: DPoP ` olarak, belirtecin anahtarına ait bir kanıtla (`ath` ile birlikte) gönderin. Gövdede ise `flow` alanına `organization_switch`, yukarıdaki DPoP ile bağlanan başsız alanları (belirtecin uygulamasının `client_id` değeri, `redirect_uri`, `code_challenge`, `state`, `nonce`, `scope`) ve `organization` alanına `GET /fapi/v1/me/organizations` uç noktasından alınan bir kuruluşun `org_…` kimliğini yazın. İstek, oturumu yeniden kullanan bir girişte olduğu gibi, belirtecin oturumuyla hemen karara bağlanır: kuruluşun ilkesi (MFA, boşta kalma sınırı, SSO, IP listesi), onay ve bekleyen yasal belgeler kontrol edilir. Yanıt, `authorization_response` içeren `completed` durumunda bir işlemle `201` olur; `code` değerini `code_verifier` değeriniz ve aynı anahtarın kanıtıyla belirteç uç noktasında değiştirin. Yeni belirteçler kuruluşu `org_id` alanında taşır. Açık kalan bir işlem olmaz ve çerez ayarlanmaz. ```json { "schema_version": 1, "state": "completed", "next_steps": [], "authorization_response": { "code": "", "state": "", "iss": "https://example.keenauth.app" }, "expires_at": "2026-10-05T10:15:00Z" } ``` | Durum | Kod | Ne zaman | | --- | --- | --- | | 401 | `unauthenticated` | Belirteç geçersiz, süresi dolmuş, iptal edilmiş veya bir anahtara bağlı değil; uygulaması etkin bir birinci taraf uygulama değil; ya da oturumu sona ermiş. | | 422 | `validation_failed` | `flow` değeri `organization_switch` değil, `client_id` belirtecin uygulaması değil, `organization` bir `org_…` kimliği değil ya da kullanıcı bu uygulamada o kuruluşa geçemiyor (`not_eligible`). | | 403 | `authorization_failed` | Kuruluş, geçişin gösteremeyeceği bir ekran gerektiriyor; `error` alanı OAuth hatasıdır (`login_required`, `interaction_required`, `consent_required`). `organization` ayarlı yeni bir giriş başlatın. | Belirteç olmadan `flow` değeri `organization_switch` olursa `422 validation_failed` (`access_token_required`) döner. ## Hatalar | Durum | Kod | Ne zaman | | --- | --- | --- | | 400 | `malformed_request` | `Idp-Client` eksik ya da gövde geçerli bir JSON değil. | | 403 | `origin_not_allowed` | `Origin` giriş sunucusu değil. | | 403 | `headless_not_allowed` | Üçüncü taraf bir uygulama başsız bir akış başlatmaya çalıştı. | | 404 | `not_found` | Sunucu hiçbir ortamın giriş sunucusu değil. | | 422 | `validation_failed` | `client_id` bu ortamın bir uygulaması değil, `redirect_uri` bu uygulama için kayıtlı değil ya da bir alan geçersiz. | | 401 | `invalid_dpop_proof` | `DPoP` kanıtı eksik, geçersiz ya da yeniden kullanılmış ya da sunucu DPoP ile bağlanan işlemleri sunmuyor. | | 401 | `use_dpop_nonce` | `DPoP-Nonce` yanıt üstbilgisinin değerini kullanarak yeni bir kanıt imzalayın. | | 503 | `temporarily_unavailable` | Bir bağımlılık kullanılamıyor; daha sonra tekrar deneyin. | ## Örnek ```bash curl -X POST https://example.keenauth.app/fapi/v1/transactions \ -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \ -H "Origin: https://example.keenauth.app" \ -H "Content-Type: application/json" \ -c cookies.txt \ -d '{"client_id":"","redirect_uri":"https://app.example.com/callback"}' ``` ## Kişisel veriler Bu uç nokta kişisel veri içerir: son kullanıcı profili. [KeenAuth API'lerinde kişisel veriler](/docs/policies/personal-data) bölümünde neyin saklandığı, ne kadar süreyle tutulduğu ve nasıl silindiği açıklanır. Hiçbir alanda özel nitelikli kişisel verileri (sağlık, biyometrik veriler, din, siyasi görüşler, cinsel yönelim) göndermeyin.