Passkey kaydını başlatın

POST /fapi/v1/me/passkeys/registration-options · ortamın giriş ana makinesinden çağrılır

Hesap portalındaki kimliği doğrulanmış kullanıcı için bir WebAuthn kaydı açar ve navigator.credentials.create fonksiyonuna iletilecek seçenekleri döndürür. Kaydı POST /fapi/v1/me/passkeys ile tamamlayın. Kayıt 5 dakika geçerlidir, yalnızca bir kez tamamlanabilir ve yalnızca onu başlatan oturum tarafından tamamlanabilir. Kimliği doğrulanmış kullanıcının __Host-idp_session çerezi gerekir; çerez eksik, süresi dolmuş veya iptal edilmişse 401 unauthenticated döner. Farklı bir kökendeki birinci taraf uygulama bunun yerine Front API erişim belirtecini gönderebilir (DPoP kanıtıyla birlikte Authorization: DPoP <token>; bkz. Front API erişim belirteci).

Oturumun passkey için son 10 dakika içinde, güvenlik anahtarı için son 5 dakika içinde doğrulanmış olması gerekir. Kullanıcının zaten ikinci bir faktörü varsa oturum ayrıca ikinci faktörle açılmış olmalıdır (urn:idp:acr:mfa): yeni bir passkey, onu ekleyen oturumun güvence düzeyini yükseltemez.

İstek

Üstbilgiler:

Üstbilgi Zorunlu Açıklama
Idp-Client evet SDK tanımlayıcısı.
Origin evet Tam olarak https://<giriş ana makinesi> olmalıdır.
Content-Type evet application/json.

Gövde:

Alan Tür Zorunlu Açıklama
role string evet passkey: tek başına giriş yapan bir kimlik bilgisi (ortamda passkey ile giriş açık olmalıdır). security_key: yalnızca ikinci faktör olarak kullanılan bir kimlik bilgisi (ortamda güvenlik anahtarı ikinci faktörü açık olmalıdır).

Yanıt

200 OK:

{
  "ceremony_id": "CQAAAAAAAAAAAAAAAAAAAA",
  "options": {"publicKey": {"challenge": "…", "rp": {"id": "example.keenauth.app", "name": "Example"}, "user": {"id": "…", "name": "ada@example.org", "displayName": "ada@example.org"}, "pubKeyCredParams": [], "timeout": 300000, "excludeCredentials": [], "authenticatorSelection": {}, "attestation": "none", "extensions": {"credProps": true}}}
}

options.publicKey değerini PublicKeyCredential.parseCreationOptionsFromJSON fonksiyonuna, sonucu navigator.credentials.create fonksiyonuna iletin. excludeCredentials, bu taraf (relying party) için kullanıcının kimlik bilgilerini listeler; böylece aynı kimlik doğrulayıcı iki kez kaydedilmez.

Hatalar

Durum Kod Ne zaman
400 malformed_request Gövde geçerli JSON değil.
400 unknown_field Gövdede role dışında bir alan var.
401 unauthenticated Geçerli oturum çerezi yok.
401 step_up_required Oturum çok eski veya ikinci faktör gerekli; WWW-Authenticate üstbilgisindeki max_age (ve uygunsa acr_values) ile yeniden doğrulayın.
403 origin_not_allowed Origin eksik veya yanlış.
403 no_allowed_method Ortam bu role değerine izin vermiyor.
409 credential_limit_reached Kullanıcının passkey ve güvenlik anahtarı sayısı en yüksek sınıra ulaşmış.
413 payload_too_large Gövde çok büyük.
415 unsupported_media_type Content-Type application/json değil.
422 validation_failed role eksik veya passkey ya da security_key değil.
422 aaguid_not_allowed Ortamın kimlik doğrulayıcı izin listesi geçersiz; düzeltilene kadar kayıt engellenir.

Örnek

curl -X POST https://example.keenauth.app/fapi/v1/me/passkeys/registration-options \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"role": "passkey"}'

Kişisel veriler

Bu uç nokta kişisel veri içerir: kimlik bilgileri. KeenAuth API'lerinde kişisel veriler 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.