コアコンセプト

本ガイドは、開発者が次のことを理解する手助けをします：あなたはどの層の拡張に属するのか、どの統合モードを取るのか、wsa トークンには何が含まれるのか、そして「どの程度まで使いたいのか」。

2 つの統合モード：プッシュ vs プル

プラットフォームが ID をあなたへ引き継ぐ経路は 2 つあります。同一の wsa 契約 で、違いは「ID 認証情報をどのように受け取るか」だけです。

プッシュ（Push handoff）—— 03 を参照

ユーザーが ワークスペースの「拡張」ページであなたのアプリを開き、プラットフォームが wsa をあなたのランディングページ URL に組み込んでプッシュします：

https://app.example.com/landing?wsa=<JWT>

                      
                      https://app.example.com/landing?wsa=<JWT>

このコードブロックをポップアップで表示

入口は ワークスペース内 にあります。
開発者はランディングページで ?wsa= を消費するだけでよく、最もシンプルです。
適した用途：ワークスペースのサイドバーに配置する「埋め込みアプリ」として。

プル（Pull / M-Auth）—— 04 を参照

開発者の拡張アプリが 自ら「Login with Workspace」ボタンを設置 し、ユーザーがクリックすると GPTBots のログイン➡️ワークスペース選択➡️ログイン状態を持ち帰ります。OAuth2 認可コード + PKCE を採用します：

入口は 開発者の拡張アプリのログインページ にあります。
ブラウザは使い捨ての code を受け取るだけで、本物の wsa は あなたのバックエンド が code + PKCE で交換し、ブラウザの URL には決して入りません。
適した用途：開発者の拡張アプリが独立したサイトで、「GPTBots ワークスペースアカウントでログイン」を提供したい場合。

	プッシュ Push	プル Pull (M-Auth)
ログイン入口	ワークスペース「拡張」ページ	あなたのアプリのページ（ログインボタン）
トークンがどう手元に届くか	URL `?wsa=` でランディングページに直接プッシュ	フロントエンドが `code` を取得、バックエンドが `wsa` に交換
ブラウザが `wsa` を見たか	見た（ランディング後すぐ消去が必要）	一度もない（より安全）
PKCE が必要か	不要	必要（`S256` 強制）
SDK フロントエンドメソッド	`consumeHandoff`	`startWorkspaceLogin` + `completeWorkspaceLogin`

ID 認証情報の使用ガイド

プラットフォームは「ID の受け渡し」だけを担い、使うかどうかは開発者が独立して決定 します：

段階	意味	開発者がすること
`use`	署名検証 + セッション確立 + `role` に応じた機能のゲート制御	`consumeHandoff` / `completeWorkspaceLogin`、バックエンドで `verifyWsa`
`receive-only`	表示/計測用に ID を読むが、セッションは作らずゲート制御もせず、引き続き自前の認証または匿名を使う	`readHandoffToken()` のみ（純粋関数、副作用なし）
`ignore`	まったく読まず、`auth_mode=none` と同等。ただの通常の外部リンク	何もしない

verifyWsa / readHandoffToken はどちらも純粋関数なので、「受け取るが使わない」はコストゼロです。

登録時の auth_mode に対応します：

auth_mode = workspace_account：プラットフォームが wsa に署名して URL に組み込む（プッシュ）/ M-Auth をサポート（プル）ため、ID を取得できます。
auth_mode = none：プラットフォームは直接リダイレクトし、URL には いかなる認証情報も付きません。ID を受け取れません（ignore に対応）。

`wsa` トークン契約（JWT）

wsa は HS256（HMAC-SHA256）で署名された JWT で、有効期限は 5 分（exp = iat + 300）です。

標準クレーム

クレーム	型	説明
`iss`	string	固定値 `gptbots-workspace`、必須検証
`aud`	string	開発者拡張アプリの host（例：`app.example.com`）。登録 URL から解析、必須検証
`sub`	string	ワークスペースユーザーの `accountId`、グローバルに一意。開発者側のユーザー ID の主キーとして使える
`iat`	number(秒)	発行時刻
`exp`	number(秒)	有効期限、固定で `iat + 300`、必須検証

業務クレーム

クレーム	型	説明
`role`	string	`OWNER` / `ADMIN` / `MEMBER` —— そのワークスペースにおけるユーザーのロール
`workspace_id`	string	ワークスペース ID（すなわち `projectId`）、マルチテナント分離キー
`username`	string	ユーザーのニックネーム（欠落する可能性あり）
`email`	string	ユーザーのメールアドレス（欠落する可能性あり）
`avatar`	string	アバター URL（欠落する可能性あり）
`app_name`	string	今回の遷移に対応する拡張アプリ名（監査に便利、欠落する可能性あり）

欠落フィールド：username / email / avatar / app_name は、ソースデータが空の場合 payload に 出現しません。必ず null 値のフォールバックを行い、それらが必ず存在するとは仮定しないでください。

payload の例

{ "iss": "gptbots-workspace", "aud": "app.example.com", "sub": "65f7c8a1d8f3a40012345678", "iat": 1730000000, "exp": 1730000300, "username": "張三", "email": "zhangsan@example.com", "avatar": "https://cdn.example.com/avatar/u123.png", "role": "ADMIN", "workspace_id": "65a0000000000000000abcde", "app_name": "契約審査システム" }

                      
                      {
  "iss": "gptbots-workspace",
  "aud": "app.example.com",
  "sub": "65f7c8a1d8f3a40012345678",
  "iat": 1730000000,
  "exp": 1730000300,
  "username": "張三",
  "email": "zhangsan@example.com",
  "avatar": "https://cdn.example.com/avatar/u123.png",
  "role": "ADMIN",
  "workspace_id": "65a0000000000000000abcde",
  "app_name": "契約審査システム"
}