# 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`](./register) 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](/docs/api/fapi/front-api-token)).

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

```json
{
  "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

```bash
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](/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.