OAuth 2.1
「Discordでログイン」のように、ほかのアプリのユーザーがBot-Hostingアカウントでログインできるようにします。OAuth 2.1とPKCEに基づくため、標準的なOAuthクライアントならどれでも使えます。
自分のアカウントを操作するにはAPIキーを使います。ほかの人のアカウントで動作するアプリを作る場合はOAuthを使うと、キーを貼り付けてもらう代わりに、ログインして同意してもらえます。ChatGPTなどのAIアシスタントも、まさにこの流れで接続します。
フロー
- 01 アプリを作成 開発者設定で名前とリダイレクトURIを登録します。シークレットなしの公開client_idが発行されます。
- 02 ユーザーを認可画面へ PKCEを付けて/oauth/authorizeにリダイレクトします。ユーザーはログインしてスコープを承認します。
- 03 コードを交換 ユーザーがcode付きで戻ってきます。それをトークンエンドポイントにPOSTして、アクセストークンを取得します。
- 04 ユーザーとしてAPIを呼び出す トークンをBearerとして/api/v1に送り、バックグラウンドで更新します。
エンドポイント
| エンドポイント | 用途 |
|---|---|
| GET /oauth/authorize | ユーザーの同意画面。ブラウザーで開きます。 |
| POST /api/oauth/token | コードをトークンに交換、またはトークンを更新します。 |
| POST /api/oauth/register | Dynamic Client Registration(RFC 7591)。任意です。 |
| GET /.well-known/oauth-authorization-server | ディスカバリーメタデータ。 |
| GET /.well-known/oauth-protected-resource | リソースメタデータ。MCPクライアントが使用します。 |
トークンの有効期間
認可コード 10分 1回限り有効で、PKCEに紐付きます。
アクセストークン 7日 /api/v1の呼び出しに使うBearer。
リフレッシュトークン 30日 使用のたびにローテーションされます。
更新
更新のたびに新しいリフレッシュトークンが返され、古いものは無効になります。保存済みのトークンは必ず上書きしてください。更新でinvalid_grantが返ったら、ユーザーを手順1からやり直してもらいます。
セキュリティ
- トークンは、ユーザーに紐付けてサーバー側に保存してください。ブラウザーや公開リポジトリには絶対に含めないでください。
- ユーザーがアプリの連携を解除すると、トークンは直ちに失効します。
- 本番環境ではhttpsのリダイレクトURIを使用してください。ローカルでのテストに限りhttpも使えます。
- 承認されたスコープにかかわらず、OAuthトークンに管理者権限は付与されません。