パスキー登録を開始する

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

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

パスキーの場合はセッションが直近 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:

{
  "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 環境の認証器許可リストが無効です。修正されるまで登録はブロックされます。

例

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 における個人データ では、保存される内容、保持期間、削除方法を説明しています。いかなるフィールドにも特別な種類の個人データ(健康、生体情報、宗教、政治的意見、性的指向)を送信しないでください。