/responses を使うチャットフロー、他のエンドポイント用のテスターを備えたローカルアプリができます。
このサンプルは Phaseo の OAuth エンドポイントを自動で検出し、戻ってきたときに state と iss を確認し、トークンを安全に更新し、ユーザーがログアウトするとキーを取り消します。
同じアプリをコーディングエージェントにゼロから作らせるには、次のプロンプトを貼り付けます。
OAuth と Phaseo 統合プロキシを備えたログイン機能付き Next.js ワークベンチを構築します。
サンプルの構成
サンプルは examples/oauth-client-nextjs にあります。
ログインと Gateway 呼び出しを分けておくと、ログインの問題がモデルの問題に見えることはなく、すべてのエンドポイントがトークンを扱う 1 か所を共有できます。
実行する
Node.js、リダイレクト URI にhttp://localhost:3000/auth/callback(または独自のコールバック)を登録した OAuth アプリ、長いランダムなセッションシークレットが必要です。OAuth アプリは 設定 → OAuth アプリ または OAuth クライアント API で作成します。
1
インストールする
2
.env.local を作成する
サンプルはこれらをすべてサーバー側でのみ読み取ります。クライアントシークレットやセッションシークレットを
NEXT_PUBLIC_ 変数に入れないでください。サンプルは、認可、トークン、取り消し、userinfo の各エンドポイントを https://api.phaseo.app/.well-known/oauth-authorization-server から見つけ、openid email profile gateway:access を要求します。gateway:access があると、トークンで Gateway を呼び出せます。3
開発サーバーを起動する
http://localhost:3000 を開いてログインし、ダッシュボードを開きます。動作を確認する
- ログインするとコールバック URL に戻り、セッションが作成されます。
- ダッシュボードが
/api/gateway/modelsを通じてモデルを一覧表示します。 /api/gateway/responsesを通したチャットのターンで回答が返り、ブラウザーのリクエストにはアクセストークンが含まれません。- プロキシの許可リストにないパスは拒否されます。
トークンの有効期間
トークンエンドポイントは 2 つのトークンを返します。- 更新のたびにローテーションする。 更新するたびに、新しいアクセストークンと新しいリフレッシュトークンが返ります。両方を保存し、古いものは破棄してください。古いアクセストークンはすぐに使えなくなり、古いリフレッシュトークンは再利用できません。
- 期限切れ後に更新する。 リフレッシュトークンが期限切れでなければ、アクセストークンの期限が切れた後でも更新できます。
- リフレッシュトークンを再利用しない。 同じリフレッシュトークンを 2 回使うと、そのログインは終了します。Phaseo はそれを漏えいしたトークンとして扱い、そのログインのアクセストークンとすべてのリフレッシュトークンを取り消すため、ユーザーは再ログインが必要になります。
- スコープは減るだけ。 更新でスコープが追加されることはありません。ユーザーが承認したスコープから、その後に外したものを除いたスコープが維持されます。
- 更新に失敗する場合。 ユーザーがアプリを取り消した、キーを取り消すか無効にした、キーに必要なスコープ(
gateway:accessなど)を外した、またはワークスペースを離れた時点で、更新は失敗します。gateway:accessを外すとキーも取り消されるため、そのアクセストークンはすぐに使えなくなります。スコープを再度付与しても、リフレッシュトークンは戻りません。ユーザーにもう一度ログインしてもらってください。 - 再ログインでキーが更新される。
resource=https://api.phaseo.app/v1を送るかどうかにかかわらず、キーを追加するのではなく同じキーを更新します。新しいアクセストークンとリフレッシュトークンが発行されて以前のものは使えなくなり、キーは今月の支出額を引き継ぎます。月間の支出上限は、ユーザーが今回承認した値になります。以前のログインのリフレッシュトークンは単に拒否され、それをトークンエンドポイントや取り消しエンドポイントに送っても新しいログインは終了しません。 - 一時停止中のキーはログインを妨げる。 そのユーザーとワークスペースに対するアプリのキーのいずれかが一時停止中の場合、リソースに関係なく、誰かが 設定 → APIキー でキーを再び有効にするまで、トークンエンドポイントは
invalid_grantを返します。更新が機能するのはキーが取り消されていない間だけです。ログアウトなどで取り消された後にログインすると新しいキーが発行され、上限と支出額は最初からになります。 - ログアウトには取り消しを使う。 リフレッシュトークンを
https://api.phaseo.app/oauth/revokeに送ります。これにより、キーと、そのログインのすべてのリフレッシュトークンが取り消されます。直前の更新で発行されたものも含まれます。
支出上限
同意画面で、ユーザーはアプリの月間支出上限を設定します。既定は $20.00 で、別の金額や上限なしも選べます。キーが暦月内にその額を使い切ると、翌月になるか、ユーザーが 設定 → APIキー で上限を引き上げるまで、Gateway リクエストはkey_limit_exceeded とともに 429 を返します。
どのスコープを持っていても、アプリが API を通じてこの上限を解除したり回避したりすることはできません。アプリにできるのは API キーの名前変更と削除だけです。キーの作成やローテーション、キーの上限・ステータス・有効期限の変更、管理キーや信頼済みワークロードの作成、メンバーの追加、予算・ガードレール・レート制限・支出ルールの変更、ワークスペースのルーティング用価格上限や BYOK からクレジットへのフォールバックの変更はできません。
公開する前に
- 許可リストを絞り込む。
lib/gateway.tsは、ワークベンチが呼び出すパスに加えて、videos/とmusic/generate/以下のジョブステータスを許可しています。製品が呼び出すパスだけを残してください。 - 更新をインスタンス間で共有する。
lib/oauth.tsは、並行するリクエスト間で 1 回の更新をメモリー内で共有します。サーバーインスタンスを複数実行する場合は、これを共有ストレージに移してください。そうしないと、2 つのインスタンスが同じトークンで更新し、ログインが終了することがあります。 - 会話全体を送る。 Gateway はレスポンスを保存せず、
previous_response_idを拒否します。以前のターンはinputに含めて再送してください。 - テスターを置き換える。 ワークベンチは社内 QA 用に残し、エンドユーザー向けには目的に合わせたフローを作ってください。