サインイントランザクションを作成

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

アプリケーションのサインイントランザクションを開始します。ホスト型サインインページ、UI コンポーネント、ヘッドレスクライアントは、環境のサインインホスト（keenauth.app のサブドメインまたは確認済みのカスタムドメイン）でこのエンドポイントを呼び出します。レスポンスでは、トランザクション Cookie __Host-idp_ltx（Secure、HttpOnly、SameSite=Lax、有効期間 15 分）が設定され、後続の手順はこの Cookie を使用します。

リクエスト

ヘッダー:

Header	Required	Description
`Idp-Client`	yes	SDK 識別子。形式は `<package>/<version> (<runtime>/<version>)` です。
`Origin`	yes	正確に `https://<sign-in host>` である必要があります。

ボディ:

Field	Type	Required	Description
`client_id`	string	yes	アプリケーションのクライアント ID。
`redirect_uri`	string (URI)	yes	アプリケーションに登録済みのリダイレクト URI のいずれか。

レスポンス

201 Created でトランザクションオブジェクトを返します:

{
  "schema_version": 1,
  "state": "identifier_pending",
  "next_steps": [{ "step": "identifier", "fields": ["identifier"] }],
  "csrf_token": "<token>",
  "expires_at": "2026-10-05T10:15:00Z"
}

このトランザクションの状態を変更するすべてのリクエストでは、csrf_token を Idp-Csrf-Token ヘッダーで送り返してください。

認可リクエストで SSO が必要な組織が指定されている場合、回答はすでに federated_redirect と redirect_url になっている場合があります（接続が 1 つの場合: トップレベルウィンドウをそこへ移動してください）。または sso_connections を含む場合があります（複数の場合: sso_start 手順で選択内容を送信してください）。

DPoP にバインドされたヘッドレストランザクション

自社のオリジンで動作するファーストパーティの SPA またはネイティブアプリは、DPoP ヘッダー（RFC 9449）を付けてヘッドレスサインインを開始します。このプルーフは、クライアントが保持する鍵（ブラウザーでは抽出不可の WebCrypto 鍵、デバイスではプラットフォームの鍵ストア）で署名され、htm は POST、htu は https://<sign-in host>/fapi/v1/transactions です。トランザクションは Cookie ではなくその鍵にバインドされます。この場合 Cookie は設定されず、オブジェクトに csrf_token は含まれません。トランザクションの後続のすべてのリクエストでは、同じ鍵から新しいプルーフを送信してください。

認可エンドポイントのルールで検証される追加のボディフィールド:

Field	Type	Required	Description
`code_challenge`	string	yes	PKCE S256 チャレンジ（RFC 7636）。
`code_challenge_method`	string	yes	`S256`。
`scope`	string	no	スペース区切りのスコープ（例: `openid profile email offline_access`）。
`state`	string	no	認可コードとともに返されます。
`nonce`	string	no	ID トークンの `nonce`。
`organization`	string	no	組織の ID または名前。
`ui_locales`	string	no	優先言語。
`resource`	string (URI)	no	リソースインジケーター（RFC 8707）。

Origin はサインインホスト、またはアプリケーションの許可された Web オリジンのいずれかです。ネイティブアプリは何も送信しません。開始できるのはファーストパーティのアプリケーションだけです。認可エンドポイントが拒否したフィールドは、422 validation_failed を返し、errors[].code に OAuth エラーコードが含まれます。サーバーが 401 use_dpop_nonce を返した場合は、DPoP-Nonce レスポンスヘッダーの値を使って新しいプルーフに署名し、再試行してください。DPoP ヘッダーなしでこれらのフィールドを送信すると、422 validation_failed（dpop_required）を返します。

組織の切り替え

サインイン中のユーザーのフロント API アクセストークンを保持しているアプリケーション（フロント API アクセストークンを参照）は、画面を表示せずにユーザーを別の組織へ切り替えられます。トークンを Authorization: DPoP <token> で送信し、トークンの鍵のプルーフ（ath を含む）を添えてください。ボディには flow に organization_switch を指定し、上記の DPoP バインドされたヘッドレスフィールド（トークンのアプリケーションの client_id、redirect_uri、code_challenge、state、nonce、scope）と、GET /fapi/v1/me/organizations から取得した組織の org_… ID である organization を含めます。

このリクエストは、セッションを再利用するサインインと同様に、トークンのセッションを使って直ちに判定されます。判定対象は、組織のポリシー（MFA、アイドル制限、SSO、IP リスト）、同意、保留中の法的文書です。回答は 201 で、authorization_response を含む completed トランザクションです。その code を、code_verifier と同じ鍵のプルーフとともにトークンエンドポイントで交換してください。新しいトークンには org_id に組織が含まれます。開いたままのトランザクションは残らず、Cookie も設定されません。

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

Status	Code	When
401	`unauthenticated`	トークンが無効、期限切れ、取り消し済み、または鍵にバインドされていない、そのアプリケーションが有効なファーストパーティアプリケーションでない、またはそのセッションが終了している。
422	`validation_failed`	`flow` が `organization_switch` でない、`client_id` がトークンのアプリケーションでない、`organization` が `org_…` ID でない、またはこのアプリケーションでユーザーがその組織へ切り替えられない（`not_eligible`）。
403	`authorization_failed`	組織が切り替えでは表示できない画面を必要とする。`error` は OAuth エラー（`login_required`、`interaction_required`、`consent_required`）。`organization` を設定して新しいサインインを開始してください。

トークンなしで flow に organization_switch を指定すると、422 validation_failed（access_token_required）を返します。

エラー

Status	Code	When
400	`malformed_request`	`Idp-Client` がないか、ボディが有効な JSON ではない。
403	`origin_not_allowed`	`Origin` がサインインホストではない。
403	`headless_not_allowed`	サードパーティのアプリケーションがヘッドレスフローを開始しようとした。
404	`not_found`	ホストがどの環境のサインインホストでもない。
422	`validation_failed`	`client_id` がこの環境のアプリケーションではない、`redirect_uri` がそのアプリケーションに登録されていない、またはフィールドが無効。
401	`invalid_dpop_proof`	`DPoP` プルーフがない、無効、または再利用されている、またはホストが DPoP にバインドされたトランザクションを提供していない。
401	`use_dpop_nonce`	`DPoP-Nonce` レスポンスヘッダーの値を使って新しいプルーフに署名してください。
503	`temporarily_unavailable`	依存先が利用できない。後で再試行してください。

例

curl -X POST https://example.keenauth.app/fapi/v1/transactions \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"client_id":"<client_id>","redirect_uri":"https://app.example.com/callback"}'

個人データ

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