Skip to content
Last updated

Gateway Token と Chat Access Token

WebDesktop

SDK App は2つの資格情報を使います。一方はブラウザに渡しても安全で、もう一方はそうではないため分かれています。Gateway Token はサーバーが持つチャネルへの長期的な鍵で、Chat Access Token は会話1つだけのための短命な資格情報です。静的トークン方式の MCP エンドポイントが使うのは前者だけです。Gateway Token を毎回のリクエストのヘッダーに付け、Chat Access Token は発行されません。OAuth 方式の MCP エンドポイントはどちらも使いません。利用者がアクセスを許可したときに、各クライアントが自分の認証情報を取得するためです。このページでは、それぞれが何を許可し、どれだけ有効で、ローテーションや失効をしたときに何が起きるのかを説明します。

どちらの資格情報をアーキテクチャのどこに置くかを決める前に読んでください。アプリケーションをデプロイした後では変更が難しく、資格情報が盗まれたときの被害の大きさを決めるのは主にこの判断です。

2つの資格情報

項目 Gateway Token Chat Access Token
接頭辞tasgwt_tascat_
保持者自社のサーバーまたは MCP クライアント。ブラウザやモバイルアプリには置きません自社のサーバー、または許可すればクライアント
スコープSDK App 1つ、または MCP エンドポイント1つ — つまり共有作業フォルダ1つと実行者1人、チャットは何件でもチャット1つ。それ以外は何も許可しません
発行者実行者またはチャネルのフォルダの管理者が、Treasure AI Studio のチャネルのページから発行SDK App でサーバーがチャットを作成したときに Agent Gateway が自動発行。MCP エンドポイントでは使いません
有効期間期限切れか失効まで。期限は発行時に選択し、無期限も選べます未使用のまま24時間、使用で延長、絶対上限は30日
できることSDK App:チャットの作成、Chat Access Token の再発行と失効、チャットの状態取得、チャットのアーカイブ。MCP エンドポイント:6つのツールの呼び出しプロンプトの送信、ターンの停止、会話の読み取り

Gateway Token 自体はスコープを持ちません。フォルダと実行者はチャネルが固定しているので、トークンは誰かがすでに同意した取り決めを使うための鍵にすぎません。そのため2本目を発行しても新しい権限は生まれず、ローテーションが安全になります。

Gateway Token を発行する

チャネルの最初のトークンは作成ウィザードが発行します。2本目以降はチャネルの詳細ページから発行します。設定 → エージェントチャネルを開き、チャネルを開いて、トークン セクションの トークンを発行 を選択します。発行できるのは、そのチャネルの実行者と、フォルダの管理者です。

有効期限はその時点で選択し、後から変更できません。

  • 7 日 / 30 日 / 90 日 — 既定は90日です。期限を付けておくことを推奨します。ローテーションを忘れたトークンが、無期限に有効なまま残るのではなく、期限で使えなくなるためです。
  • カスタム日付 — 個人タイムゾーンでのその日の終わり (23:59:59) に確定します。そのタイムゾーンで明日以降の日付である必要があります。
  • 無期限 — 失効させるまで有効です。監視しているサーバー統合には妥当ですが、期限に頼らずローテーションを回す運用があることが前提です。

ここで使われるタイムゾーンは、設定ページの Timezone です。お使いの端末の設定ではありません。つまり「21日まで」のトークンは、あなたが日付を読む基準での21日の終わりを意味し、フィールドにはそのタイムゾーン名も表示されます。有効期限は正確な時刻として保存されるので、時差のある同僚のところでずれることはなく、トークン一覧の 有効期限 も自分のタイムゾーンで表示されます。

シークレットは一度だけダイアログに表示され、閉じる前に 値を保存しました で確認する必要があります。MCP エンドポイントの場合は、クライアントにそのまま貼り付けられるよう、認証ヘッダー(Authorization: Bearer tasgwt_…)の形で表示されます。以降チャネルに表示されるのはヒント(末尾の数文字)だけで、行を見分けたりサポートへの問い合わせで特定したりするには足りますが、それ以上のことはできません。Treasure AI Studio はダイジェストのみを保存するため、紛失したトークンはサポートを含め誰も復元できません。

各トークンの行には 最終使用 も表示されます。更新は最大で1時間に1回です。SDK App では、その Gateway Token で発行した Chat Access Token が使われたときに更新され、チャットの作成などコントロール API の呼び出しでは更新されません。MCP エンドポイントでは、そのトークンでリクエストしたときに更新されます。利用されていないトークンを特定するのに有用です。失効させる前に確認してください。

Gateway Token をローテーションする

1つのチャネルは複数のトークンを同時に持てるため、ローテーションを安全に行えます。チャネル配下のトークンはすべて同じスコープなので、新しいトークンが届く範囲は古いものとまったく同じです。

  1. チャネルの詳細ページで新しいトークンを発行し、保管します。
  2. 新しいトークンでサーバーをデプロイするか、MCP クライアントのヘッダーを更新します。
  3. SDK App のみ: 使用中のチャットについて、新しい Gateway Token で Chat Access Token を発行し直します(POST /v1/chats/{chat_id}/access_tokens)。古い Gateway Token を失効させると、それで発行したすべての Chat Access Token が止まり、それを使っている会話が途切れるためです。
  4. 新しいトークンの 最終使用 が動き、古いほうが止まっていることを確認します。最終使用 の更新は最大で1時間に1回なので、1時間以上おいてから確認してください。
  5. 古いトークンを失効させます。
ローテーション後のトークン一覧。失効済みの行と有効な行が並び、それぞれヒント、発行日と発行者、有効期限、最終使用が表示され、失効アイコンは有効な行にだけある

デプロイ前に失効させないでください。失効したトークンに猶予期間はなく、失効を取り消す方法もありません。

有効期限を変える手段もローテーションです。既存のトークンの期限は固定されているためです。チャネルを無期限から期限付きに移すには、期限付きのトークンを発行し、切り替えてから、無期限のものを失効させます。

トークンの失効

失効は即時かつ恒久です。失効した Gateway Token は、SDK App のコントロール API でも MCP エンドポイントでも、次のリクエストから拒否されます。これらのリクエストは毎回確認されるためです。

SDK App の Gateway Token を失効させると、そのトークンから発行されたすべての Chat Access Token も1分程度で止まります。ゲートウェイがチャット用トークンの検証成功を最大60秒キャッシュしているためです。すでに開いているストリームは、つながっているターンが終わるまで配信を続け、エージェントの処理もキャンセルされません。それらの Chat Access Token を使う新しいリクエストはすべて拒否されます。MCP エンドポイントが開始したチャットは、同じエンドポイントの他のトークンから引き続き扱えます。続きの指示は、チャットを開始したトークンではなくエンドポイントに結びついているためです。

これ以外にも、トークンを失効させずに資格情報を止める操作がいくつかあります。あとで元に戻したい場合に重要です。

操作 資格情報への影響
Gateway Token を失効させるそのトークンと、そこから発行されたすべての Chat Access Token が止まります。恒久的です。チャネルの他のトークンには影響しません
チャネルを無効化する (トグルを 無効 にする)配下のすべてのトークンによる認証が止まります。トークン自体は失効しません — チャネルを再び有効にすればすべて元に戻ります
実行者から降りる同じ操作でチャネルが無効になるため、配下のすべてのトークンが止まります。トークン自体は失効しません
チャネルを削除、またはフォルダを削除すべてのトークンが使えなくなり、チャネルもなくなります。恒久的です
実行者がフォルダへのアクセスを失うその状態が続く間、トークンは認証を通りません。権限はリクエストごとに評価されます

他のユーザーに影響を与えずに特定のユーザーのセッションだけを終わらせたい場合は、Gateway Token ではなくそのチャットの Chat Access Token を失効させてください。Agent Gateway のコントロール API は、1本だけ、またはあるチャットのすべてのトークンを失効させられます。エンドポイントのリファレンスを参照してください。

Chat Access Token の有効期間

この節と次の節は SDK App だけが対象です。Chat Access Token はチャットごとに作られ、そのチャットの接続先 URL と一緒にサーバーに返されます。有効期間は次の2つの期限で決まります。

  • アイドル期限 — 既定24時間。 使うたびに先送りされるので、活発な会話は有効なままです。
  • 絶対期限 — 既定30日。 発行時に固定され、使用状況では延長されません。

先に来たほうが優先されます。実際に適用されている値は、チャネルの詳細ページの接続設定に チャットトークンのアイドル期限 と チャットトークンの最大期限 として表示され、編集 からチャネルごとに変更できます — チャネルの設定を変更するを参照してください。

トークンが期限切れになっても、チャット自体はそのままです。サーバーがコントロール API で同じチャットに対して新しいトークンを発行すれば会話は続きます。トークンだけでなくチャット ID を保存しておく価値があるのはこのためです。

ブラウザアクセス

ブラウザが SDK App のメッセージング API を呼べるかどうかは、SDK App 上の1つの設定で決まります。詳細ページでは ブラウザアクセス、ウィザードでは エンドユーザーのブラウザからのチャット操作を許可 として表示されます。既定はオフで、オフは 「サーバーのみ」 を意味します。ゲートウェイは Origin ヘッダーを伴うリクエストをすべて拒否します。

この規則の効果は、一見して分かるより広いものです。Authorization ヘッダーを伴うリクエストでは、ブラウザは Origin ヘッダーを抑制できません。したがってこの設定がオフなら、ブラウザ内で動くコードはゲートウェイに一切到達できません — 自分のページのスクリプトも、そこに混入した依存パッケージや注入されたスクリプトも同様です。サーバーが経路に残るので、そこで行っていること — 自社の認証、監査ログ、レート制限、プロンプトに対する検査 — もすべて残ります。

MCP エンドポイントにはこの設定がありません。ゲートウェイは Origin ヘッダーの付いたリクエストを常に拒否します。

オンにすることは、ページ内のコードを信頼するという判断です。ブラウザが Chat Access Token を保持してゲートウェイと直接やり取りする構成が本当に必要な場合にのみ選んでください。トレードオフの全体はトークンをどこに置くか決めるにあります。

中継サーバーはブラウザの Origin ヘッダーを転送してはいけません

サーバーでメッセージング API を中継する場合は、ブラウザのヘッダーをそのまま再送するのではなく、リクエストを明示的に組み立ててください。Origin ヘッダーを通してしまうとサーバーがブラウザに見え、ゲートウェイは「このチャットはブラウザから呼び出せません」という内容の 403 を返します。動いていた統合が壊れる原因として最も多いパターンです。

なぜ許可リストではなくオン / オフなのか

ブラウザアクセスはオン / オフの設定で、Agent Gateway は許可オリジンの一覧を持ちません。これは未実装だからではなく、許可リストのほうが弱い制御になるためです。

許可リストが決めるのは、ブラウザが応答を読めるかどうかだけで、送れるかどうかではありません。 リストに無いオリジンからのリクエストもゲートウェイに届いてプロンプトは受理され、エージェントは動きます。ブラウザは読む権限のない応答を捨てるだけです。つまり許可リストでは、本当に防ぎたいこと — 自分が管理していないページが自分のクレジットでエージェントを動かすこと — を防げず、その結果が見えなくなるだけです。

オン / オフの設定はこれを防ぎます。 ブラウザアクセスがオフなら、プロンプトが受理される前に 403 で拒否されるので、何も動きません。しかもブラウザ側からこれを回避する方法はありません。Authorization を付けたスクリプトは Origin を消せず、Authorization を付けないリクエストはそもそも認証を通りません。この保証は、自分のページのスクリプトにも、そこに注入されたコードにも等しく効きます。

想定しておくべき帰結が2つあります。

  • ブラウザアクセスをオンにすると、有効な Chat Access Token を持つオリジンはどこからでも呼び出せます。 ゲートウェイはリストと照合せず、呼び出してきたオリジンをそのまま返します。被害を限定するのはトークン側です — チャット1つに限られ、アイドル期限と絶対期限で切れます。
  • どちらの設定でも、サーバーに持ち出されたトークンは止められません。 サーバーからのリクエストには Origin が付かないため、両方のモードで通ります。これが問題になるなら、トークンをサーバー側に置いてください — 中継する構成がこの経路を閉じます。

資格情報を安全に扱う

  • Gateway Token はサーバーに置く。 シークレット管理ツールか MCP クライアントの設定に入れ、ソース管理、ビルド成果物、デバッグ用エンドポイントが出力する環境変数には置かないこと。参照先のフォルダと同程度に機密です。
  • ブラウザやモバイルアプリには絶対に配らない。 その中から、直接も自社エンドポイント経由でも取得できないようにしてください。
  • アプリケーションやチームごとにチャネルを分ける。 共用したトークンは、片方の利用者に対してだけ失効させることができません。
  • 可能なら期限を付ける。 ローテーションのリマインダーを伴う90日のトークンは、誰も見直さない無期限のトークンより優れています。
  • 最終使用を見る。 数か月呼ばれていないトークンは、忘れられたデプロイのものか、使い手のいないものかのどちらかです。いずれにしても有効のままにしておくべきではありません。
  • 漏洩は調査ではなくローテーションとして扱う。 代替のトークンを発行し、デプロイし、漏洩したトークンを失効させる。原因の解明はその後です。

次のステップ