サインインのステップを実行

POST /fapi/v1/transactions/current/steps/{step} · 環境のサインインホストから呼び出されます

現在のトランザクションの1つのステップを実行します。このバージョンではidentifierおよびpasswordのステップを受け付けます。認証情報のステップが失敗すると、いずれも同じ401 invalid_credentialsを返すため、レスポンスからアカウントの存在は分かりません。パスワードのステップでトランザクションが完了すると、セッションCookie __Host-idp_session（必要な場合は__Host-idp_deviceも）が設定され、トランザクションCookieは削除されます。

リクエスト

ヘッダー:

ヘッダー	必須	説明
`Idp-Client`	はい	SDK の識別子。
`Origin`	はい	正確に `https://<sign-in host>` である必要があります。
`Idp-Csrf-Token`	はい	トランザクションオブジェクトの `csrf_token`。

パス: step。ステップ名（identifier、password、sso_start）。

otp_send ステップでは、next_steps[].methods に、有効なポリシーが許可しているパスワードレス方式（email_otp、magic_link）が一覧されます。クライアントはこれらのみを提示します。

ボディ（フィールドはステップによって異なります。next_steps[].fields に一覧があります）:

フィールド	型	説明
`identifier`	string	メールアドレス、電話番号またはユーザー名（`identifier` ステップ）。最大320文字。
`password`	string	パスワード（`password` ステップ）。最大128文字。
`connection_id`	string	`sso_connections[].connection_id` の値（`sso_start` ステップ）。

レスポンス

ステップ実行後のトランザクションを含む 200 OK を返します。completed のトランザクションには csrf_token がありません。

環境で第2要素が必須で、ユーザーがまだ一つも登録していない場合でも、環境のmfa.enrollment_grace_days内にいるユーザーはサインインでき、completed レスポンスには mfa_enrollment が含まれます: required_by（RFC 3339形式、猶予期間の終了時刻。サーバーが計算します）とmethods（webauthn、totp: ユーザーが今登録できる要素を画面上の順序で示したもの）。日付を表示し、ユーザーが続行できるようにしてください。登録はアカウント設定で追加されます。猶予期間がない場合、ユーザーがポリシーを満たしている場合、または登録がすぐに必要な場合は、このフィールドは含まれません。アプリケーションのmin_acrと要求されたacr_valuesは、猶予期間によって延期されることはありません。

企業SSO（ホームレルム検出）

identifier ステップで、ドメインが企業接続に属するメールアドレスを受け取った場合、サインインはその接続で続行されます。検出に使われるのは@より後の部分のみです。

接続が1つの場合: トランザクションはfederated_redirectに移行し、レスポンスにはredirect_url（ID プロバイダの開始アドレス）が含まれます。トップレベルのウィンドウをそのアドレスに移動してください。このアドレスにはワンタイムトークンが含まれるため、保存もログ記録もしないでください。
接続が複数の場合: トランザクションはidentifier_pendingのままとなり、レスポンスにはsso_connections（connection_id、display_name、protocol）が一覧されます。display_nameをテキストとして表示し、ユーザーの選択をsso_startステップ（identifierとconnection_id）で送信してください。そのドメインに提供されていない接続を指定すると、422 validation_failedが返されます。
接続がない場合、または検出が一時的に利用できない場合: 通常のサインインが続行されるため、障害によって他のサインイン方式がブロックされることはありません。sso_start は明示的な選択であり、代わりに503 temporarily_unavailable を返します。

サインインリクエストでSSOを必須とする組織が指定されている場合、トランザクションはその組織の接続のみを提供します。パスワードおよびメールの認証コードのステップは提供されず、パスキーは組織に緊急用（break-glass）アカウントがある場合にのみ利用可能なままとなります。トランザクションを作成すると、唯一の接続がすでに開始されます（federated_redirect と redirect_url の組み合わせ）、またはsso_connections に複数の接続が一覧されます。選択はsso_start と connection_id のみで送信してください。ここではidentifier は任意です。この要件の下では、検出は他の方式にフォールバックしません。企業サインインに到達できない場合、ステップは503 temporarily_unavailable を返します。メールドメインが、認証済みドメインに対してSSOを必須とする組織に属している場合も同様です。

IDプロバイダでの認証後、ブラウザはサインインホストの/u/sso/completeに戻ります。ホスト型のページがサインインを完了させます。

企業サインインを既存のアカウントにリンクする

企業接続がメールアドレスを保証せず、その接続が主張するアドレスが環境内のアカウントですでに認証済みである場合、企業サインインはセッションを開きません。ブラウザは、オブジェクトにaccount_link を含む新しいトランザクションとともにホスト型のサインインページに戻ります: connection_name と、接続が組織に属する場合はorganization_name です。ユーザーにすでにアカウントがあり、接続をリンクするにはそのアカウントにサインインする必要があることを伝えてください。アカウント名は示さないでください。このトランザクションではsso_start と magic_link は提供されず、identifier ステップは企業接続にルーティングされません。

ユーザーは既存のアカウントに、そのアカウントの方式でサインインします。第2要素を登録しているユーザーには、その入力が求められます。トランザクションを完了させるステップではセッションは開かれません。接続はアカウントにリンクされ、レスポンスは、同じ接続に対するredirect_url を含むfederated_redirect の新しいトランザクションになります。トップレベルのウィンドウをそこに移動してください。企業サインインは通常どおり完了します。企業サインインを開始できない場合、新しいトランザクションはidentifier_pending となり、通常のサインインが続きます。

別のアカウントで、登録済みの第2要素を使わずに、またはリンク要求より前に行われたサインインで完了した場合、何もリンクされず、セッションも開かれません: 409 transaction_state_conflict。期限切れ（10分）またはすでに使用されたリンク要求は410 transaction_expired を返します。リンク要求は結果にかかわらず一度だけ使用されます。辞退するにはPOST /fapi/v1/transactions/current:cancel を呼び出してください。

組織のポリシー

認可リクエストが組織に紐づいている場合、組織のサインインポリシーは、第1要素の後、セッションを開く直前に再度確認されます:

クライアントのIPアドレスが組織の許可リストに含まれていない場合: 403 ip_not_allowed。
トランザクションの要素が組織のポリシーを満たさない場合（組織が許可していない方式、要素の欠落、または組織のAAGUID許可リストに含まれないセキュリティキーもしくはパスキー）: 403 no_allowed_method。
組織のポリシーを読み取れない場合: 503 temporarily_unavailable。サインインはフェイルクローズドとなり、ポリシーなしで続行されることはありません。

セッションは開かれません。トランザクション完了時の拒否はトランザクションCookieを削除します。第1要素の後の503 はトランザクションをそのままの状態にし、ステップは再試行できます。エラー本文には、組織、ユーザー、IPアドレスのいずれも示されません。

DPoPに紐づくヘッドレストランザクション

DPoP ヘッダーで開始されたトランザクションでは、Idp-Csrf-Token の代わりに、同じ鍵から新しい証明（htm POST、htu はステップのURL）を送信してください。Cookieは使用されません。トランザクションを完了させるステップは、authorization_response を一度だけ返します:

{
  "state": "completed",
  "authorization_response": { "code": "<code>", "state": "<your state>", "iss": "https://example.keenauth.app" },
  "next_steps": [],
  "schema_version": 1,
  "expires_at": "2026-11-02T10:15:00Z"
}

state とiss が一致することを確認してから、同じ鍵によるDPoP証明とともに、/oauth2/token でコードをcode_verifier と交換してください。別の鍵による証明はinvalid_grant を返します。認可リクエストがコードで終了できない場合（同意、法的規約、組織の選択、または新しいサインインが必要な場合、もしくはアクセスが拒否された場合）、ステップは403 authorization_failed を返し、error メンバーにOAuthのエラーコードが含まれます。コードは発行されません。

エラー

ステータス	コード	発生条件
401	`invalid_credentials`	識別子またはパスワードが受け付けられません。
403	`origin_not_allowed`	`Origin` または`Idp-Csrf-Token` が欠落している、または誤っています。
403	`ip_not_allowed`	クライアントのIPアドレスが組織の許可リストに含まれていません。
403	`no_allowed_method`	サインインが組織のポリシーを満たしていません。
403	`test_feature_not_in_production`	本番環境で、`otp_verify` または`email_2fa` が固定のテスト用コード`424242` を受け取りました。試行は誤ったコードと同様にカウントされます。
404	`not_found`	ステップ名が既知のステップではありません。
409	`transaction_state_conflict`	現在の状態ではそのステップは利用できません。
409	`session_limit_reached`	ユーザーがセッション上限に達し、新しいセッションが拒否されています。
410	`transaction_expired`	トランザクションが終了しています。
422	`validation_failed`	フィールドが欠落しているか無効です。
503	`temporarily_unavailable`	`sso_start` が企業サインインに到達できなかったか、組織のポリシーを読み取れませんでした。再試行してください。
401	`invalid_dpop_proof`	`DPoP` の証明が欠落している、無効である、または再利用されています。
403	`authorization_failed`	DPoPに紐づくトランザクションは完了したものの、その認可リクエストがコードなしで終了しました。

例

curl -X POST https://example.keenauth.app/fapi/v1/transactions/current/steps/identifier \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Idp-Csrf-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"identifier":"jane@example.com"}'

個人データ

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