# Gateway Token と Chat Access Token

[Agent Channel](/ja/products/ai-studio/agent-channels) は2つの資格情報を使います。一方はブラウザに渡しても安全で、もう一方はそうではないため分かれています。**Gateway Token** はサーバーが持つチャネルへの長期的な鍵で、**Chat Access Token** は会話1つだけのための短命な資格情報です。このページでは、それぞれが何を許可し、どれだけ有効で、ローテーションや無効化をしたときに何が起きるのかを説明します。

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

## 2つの資格情報

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


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

## Gateway Token を発行する

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

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

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


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

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

各トークンの行には **最終使用** も表示されます。リクエストごとではなく粗い粒度で更新されます。利用されていないトークンを特定するのに有用です。無効化する前に確認してください。

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

1つのチャネルは複数のトークンを同時に持てるため、ローテーションは特別な作業になりません。チャネル配下のトークンはすべて同じスコープなので、新しいトークンは古いものとまったく同じように振る舞います。

1. チャネルの詳細ページで新しいトークンを発行し、保管します。
2. 新しいトークンでサーバーをデプロイします。
3. 新しいトークンの **最終使用** が動き、古いほうが止まっていることを確認します。
4. 古いトークンを無効化します。


ローテーション後のトークン一覧。無効化済みの行と有効な行が並び、それぞれヒント、発行日と発行者、有効期限、最終使用が表示され、無効化アイコンは有効な行にだけある
デプロイ前に無効化しないでください。無効化されたトークンに猶予期間はなく、無効化を取り消す方法もありません。

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

## トークンの無効化

無効化は即時かつ恒久です。ゲートウェイは資格情報の検証成功を短時間キャッシュし、リクエストごとに問い合わせはしないため、全体に行き渡るまで1分程度かかります。

Gateway Token を無効化すると、**そのトークンから発行されたすべての Chat Access Token** も止まります。その時点で開いている会話は接続を失います。エージェントがすでに実行していたターンは無効化によってキャンセルされないため、処理中だったものはサーバー側で完了します。止まるのは、クライアントからの閲覧と送信です。

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

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


他のユーザーに影響を与えずに特定のユーザーのセッションだけを終わらせたい場合は、Gateway Token ではなくそのチャットの Chat Access Token を無効化してください。Agent Gateway のコントロール API は、1本だけ、またはあるチャットのすべてのトークンを無効化できます。[エンドポイントのリファレンス](/ja/products/ai-studio/agent-channels/building-an-app#%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB-api-%E3%83%AA%E3%83%95%E3%82%A1%E3%83%AC%E3%83%B3%E3%82%B9)を参照してください。

## Chat Access Token の有効期間

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

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


先に来たほうが優先されます。実際に適用されている値は、チャネルの詳細ページの**接続設定**に **チャットトークンのアイドル期限** と **チャットトークンの最大期限** として表示され、**編集** からチャネルごとに変更できます — [チャネルの設定を変更する](/ja/products/ai-studio/agent-channels/sdk-apps#%E3%83%81%E3%83%A3%E3%83%8D%E3%83%AB%E3%81%AE%E8%A8%AD%E5%AE%9A%E3%82%92%E5%A4%89%E6%9B%B4%E3%81%99%E3%82%8B)を参照してください。

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

## ブラウザアクセス

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

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

オンにすることは、ページ内のコードを信頼するという判断です。ブラウザが Chat Access Token を保持してゲートウェイと直接やり取りする構成が本当に必要な場合にのみ選んでください。トレードオフの全体は[トークンをどこに置くか決める](/ja/products/ai-studio/agent-channels/building-an-app#%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%82%92%E3%81%A9%E3%81%93%E3%81%AB%E7%BD%AE%E3%81%8F%E3%81%8B%E6%B1%BA%E3%82%81%E3%82%8B)にあります。

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

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

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

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

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

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

- **ブラウザアクセスをオンにすると、有効な Chat Access Token を持つオリジンはどこからでも呼び出せます。** ゲートウェイはリストと照合せず、呼び出してきたオリジンをそのまま返します。被害を限定するのはトークン側です — チャット1つに限られ、アイドル期限と絶対期限で切れます。
- **どちらの設定でも、サーバーに持ち出されたトークンは止められません。** サーバーからのリクエストには `Origin` が付かないため、両方のモードで通ります。これが問題になるなら、トークンをサーバー側に置いてください — [中継する構成](/ja/products/ai-studio/agent-channels/building-an-app#%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%82%92%E3%81%A9%E3%81%93%E3%81%AB%E7%BD%AE%E3%81%8F%E3%81%8B%E6%B1%BA%E3%82%81%E3%82%8B)がこの経路を閉じます。


## 資格情報を安全に扱う

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


## 次のステップ

- [Vercel AI SDK でチャットアプリを作る](/ja/products/ai-studio/agent-channels/building-an-app) — これらの資格情報をコードで使う
- [SDK App の作成と管理](/ja/products/ai-studio/agent-channels/sdk-apps) — 画面からの発行と無効化
- [Agent Channel のチャットが到達できる範囲](/ja/products/ai-studio/agent-channels/channel-chats) — 資格情報の保持者が実際にエージェントに何をさせられるのか