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ı, `<package>/<version> (<runtime>/<version>)`.
`Origin`	evet	Tam olarak `https://<giriş sunucusu>` 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:

{
  "schema_version": 1,
  "state": "identifier_pending",
  "next_steps": [{ "step": "identifier", "fields": ["identifier"] }],
  "csrf_token": "<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://<giriş sunucusu>/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), kullanıcıyı ekran göstermeden başka bir kuruluşa geçirebilir. Belirteci Authorization: DPoP <token> 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.

{
  "schema_version": 1,
  "state": "completed",
  "next_steps": [],
  "authorization_response": { "code": "<code>", "state": "<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

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":"<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 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.