# パスキー登録を開始する

`POST /fapi/v1/me/passkeys/registration-options` · 環境のサインインホストから呼び出し

アカウントポータルから認証済みユーザーの WebAuthn 登録を開始し、`navigator.credentials.create` に渡すオプションを返します。[`POST /fapi/v1/me/passkeys`](./register) で登録を完了します。登録は 5 分間有効で、1 回だけ完了でき、開始したセッションからのみ完了できます。認証済みユーザーの `__Host-idp_session` Cookie が必要です。Cookie がない、期限切れ、または取り消されている場合は `401 unauthenticated` を返します。別オリジンの自社アプリケーションは、代わりにフロント API アクセストークン(DPoP 証明付きの `Authorization: DPoP <token>`。[フロント API アクセストークン](/docs/api/fapi/front-api-token) を参照)を送信できます。

パスキーの場合はセッションが直近 10 分以内に、セキュリティキーの場合は直近 5 分以内に検証されている必要があります。ユーザーが既に第 2 要素を持っている場合は、セッションも第 2 要素(`urn:idp:acr:mfa`)で開始されている必要があります。新しいパスキーによって、それを追加するセッションの保証レベルを引き上げることはできません。

## リクエスト

ヘッダー:

| ヘッダー | 必須 | 説明 |
| --- | --- | --- |
| `Idp-Client` | はい | SDK の識別子。 |
| `Origin` | はい | 正確に `https://<sign-in host>` である必要があります。 |
| `Content-Type` | はい | `application/json`。 |

本文:

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `role` | string | はい | `passkey`: サインインに単独で使える認証情報(環境でパスキーサインインを有効にしている必要があります)。`security_key`: 第 2 要素としてのみ使う認証情報(セキュリティキーの第 2 要素を有効にしている必要があります)。 |

## レスポンス

`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` を `PublicKeyCredential.parseCreationOptionsFromJSON` に、その結果を `navigator.credentials.create` に渡します。`excludeCredentials` には、この Relying Party に対するユーザーの認証情報が一覧されるため、同じ認証器が二重に登録されることはありません。

## エラー

| ステータス | コード | 発生条件 |
| --- | --- | --- |
| 400 | `malformed_request` | 本文が有効な JSON ではありません。 |
| 400 | `unknown_field` | 本文に `role` 以外のフィールドがあります。 |
| 401 | `unauthenticated` | 有効なセッション Cookie がありません。 |
| 401 | `step_up_required` | セッションが古い、または第 2 要素が必要です。`WWW-Authenticate` ヘッダーの `max_age`(該当する場合は `acr_values`)を使って再検証してください。 |
| 403 | `origin_not_allowed` | `Origin` がない、または誤っています。 |
| 403 | `no_allowed_method` | 環境でこの `role` が許可されていません。 |
| 409 | `credential_limit_reached` | ユーザーがパスキーとセキュリティキーの上限数に達しています。 |
| 413 | `payload_too_large` | 本文が大きすぎます。 |
| 415 | `unsupported_media_type` | `Content-Type` が `application/json` ではありません。 |
| 422 | `validation_failed` | `role` がないか、`passkey` または `security_key` ではありません。 |
| 422 | `aaguid_not_allowed` | 環境の認証器許可リストが無効です。修正されるまで登録はブロックされます。 |

## 例

```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"}'
```

## 個人データ

このエンドポイントは個人データ(認証情報)を扱います。[KeenAuth API における個人データ](/docs/policies/personal-data) では、保存される内容、保持期間、削除方法を説明しています。いかなるフィールドにも特別な種類の個人データ(健康、生体情報、宗教、政治的意見、性的指向)を送信しないでください。