logo
Development
概要開発スペースワークスペースAPI Referenceベストプラクティス更新履歴
検索
日本語
API Reference / 拡張アプリログイン / トラブルシューティング
07 · よくある質問とトラブルシューティング
最終更新日：13日前

07 · よくある質問とトラブルシューティング

エラーコード一覧表

verifyWsa がスローする WsaVerificationError.code

code よくある原因 調べ方
InvalidSignature シークレットの誤り、トークンの改ざん、Tier1/Tier2 のシークレット取り違え バックエンドで使うシークレットが登録/配布されたものと一致するか確認する；per-app シークレットは 文字列をそのまま 渡し、hex デコードしない
WrongAudience audience がトークンの aud と不一致 audience は登録 URL の host（例：app.example.com）と厳密に一致しなければならず、ポート/プロトコルを含まない
WrongIssuer issuer の設定が変更された デフォルトの gptbots-workspace を維持する
Expired トークンが 5 分を超過、サーバーの時計のずれ サーバーの時計を NTP 同期する；wsa は使い捨ての誘導トークンなので、キャッシュして後で使い回さない
NotYetValid iat/nbf が未来 通常は署名側/検証側の時計が大きく同期していない
MissingClaim exp/sub/role/workspace_id が欠落 正常なプラットフォームトークンは欠落しない；出現したらトークンの出所が疑わしい
UnsupportedAlgorithm alg がホワイトリスト外 デフォルトは HS256 のみ；RS256 は明示的に algorithms:['RS256'] + publicKey が必要
InvalidToken トークンが空/構造が不正/切り詰められている フロントエンドが完全な wsa を正しく取得できているか、URL が中間層で書き換えられていないか確認する

/token 交換段階（プル）

code 意味 発生条件
403209 Invalid grant code の欠落、期限切れ、または使用済み（リプレイ）。code は一度しか使えない
403210 Invalid verifier PKCE codeVerifier が開始時の code_challenge と不一致

プッシュ sign-token（ワークスペースのフロントエンドが呼び出す、参考まで）

code 意味 発生条件
40000 Parameter error URL が未登録、auth_mode が workspace_account でない
40100 Permission deny 未ログインまたはセッション失効
40105 Require member of project クリックした人がそのワークスペースのメンバーでない
40320 Member not found アカウントが登録解除/削除された

FAQ

Q：プッシュとプル、どちらを選ぶべき？
A：入口がワークスペースの「拡張」ページ内にあり、「埋め込みアプリ」にしたい → プッシュ（最もシンプル）。あなたのアプリが独立したサイトで「GPTBots でログイン」ボタンを設置したい → プル（M-Auth、より安全、wsa はブラウザに入らない）。02 を参照。

Q：フロントエンドで直接 JWT を解いてユーザー情報を取得できる？
A：展開して見ることはできますが、信頼できる ID として扱ってはいけません——シークレットがなければ署名検証できず、payload は偽造可能です。あらゆる認可判断は バックエンドの verifyWsa の結果 を基準にしなければなりません。05 §5 を参照。

Q：wsa が期限切れになったらどうする？
A：wsa は使い捨ての誘導トークン（5 分）にすぎません。ランディング時に一度検証し、自前のセッションに置き換え、その後は 常に自前のセッション を使い、wsa に依存しないでください。ユーザーが次に拡張ページから開くと新しい wsa を取得します。

Q：ランディングページの consumeHandoff が「no handoff token present」をスローする？
A：現在の URL に ?wsa= がないことを示しています——ユーザーが直接アクセスしたか、wsa が前回の交換成功で消去された可能性があります。「初回のトークン付きランディング」と「通常のアクセス」を区別し、後者は自前のログイン/匿名分岐に進めてください。

Q：プルログインのコールバックで StateMismatch / MissingRequest が出る？
A：MissingRequest = 同一ブラウザセッションで先に startWorkspaceLogin を呼んでいない（PKCE verifier は sessionStorage に保存されるため、タブを切り替えたりストレージをクリアすると失われます）。StateMismatch = コールバックの state が保存されたものと不一致（CSRF 保護）。デバイス跨ぎ/セッション跨ぎになっていないか確認してください。

Q：プルログインで CryptoUnavailable が出る？
A：PKCE には Web Crypto が必要で、セキュアコンテキスト（HTTPS または localhost）でのみ利用できます。HTTPS またはローカルの localhost でデバッグしてください。

Q：redirect_uri が invalid_request を出す / 組織選択ページに戻る？
A：redirect_uri の scheme + host は client_id（登録 URL）と厳密に同一でなければなりません。https アプリに http コールバックは設定できず、host も一致していなければなりません。プラットフォームは 決して 未検証のアドレスへ遷移しないため、組織選択ページに戻って ?error=invalid_request を付けます。

Q：per-app シークレットを HMAC key にするには？ base64/hex デコードは必要？
A：文字列をそのまま 渡してください（SDK もプラットフォームも UTF-8 バイトを直接 HMAC key にします）。Tier 2 シークレットは wext_+64 hex のような形式で、その文字列全体がシークレットです。改めてデコードしないでください。

Q：CommonJS プロジェクトで SDK を使える？
A：SDK は ESM です。CJS プロジェクトでは動的な import() を使うか、関連モジュールを ESM に変更してください。

Q：アイコン/名前はどう変更する？
A：Tier 2 はスペース管理で編集します；Tier 1 はプラットフォーム運用に連絡して辞書エントリを変更してもらいます。

Q：管理者が私のアプリを停止するとどうなる？
A：組織管理者はスペース管理でアプリを停止できます（プラットフォーム公共アプリの本組織での可視性を含む）。停止後、その組織のメンバーは拡張ページで入口を見られなくなり、プラットフォームもその組織向けに wsa を 発行しなくなります（プッシュもプルも拒否）。

結合テストチェックリスト

  • audience == 登録 URL の host（最もよくある WrongAudience の原因）
  • バックエンドのシークレットが登録/配布と一致し、かつ バックエンドにのみ ある
  • サーバーの時計が NTP 同期済み（Expired / NotYetValid の多くは時計が原因）
  • ランディング後に history.replaceState で wsa / code を消去する
  • 自前のセッションに置き換え、以降のリクエストで wsa を透過的に渡さない
  • プル：HTTPS/localhost のセキュアコンテキスト；redirect_uri と client_id が同一ドメイン
  • マルチテナントを workspace_id で分離する

参考