OAuth2 + インストール URL

GameVox の OAuth2 フローは Discord とワイヤー互換です。認可 URL、トークン交換、スコープ名、グラント種別はすべて一致します。このページでは、インストールリンクの挙動と確認画面の表示を左右する少数のフィールドを説明します。

エンドポイント

GET  https://gamevox.com/oauth2/authorize
POST https://api.gamevox.com/oauth2/token
POST https://api.gamevox.com/oauth2/token/revoke
GET  https://api.gamevox.com/oauth2/@me

クライアント認証情報

すべてのアプリケーションにクライアント ID（アプリケーションの Snowflake）とクライアントシークレットが発行されます。シークレットはアプリ作成時に一度、そしてローテーション時に一度だけ表示されます。保存されるのは bcrypt ハッシュと接頭辞・末尾 4 文字だけです。

ローテーション: POST /developer-portal/applications/{id}/reset-secret。以前のシークレットは直ちに無効になります。
パブリッククライアント（モバイルアプリ、SPA）: パブリッククライアントをオンにしてください。トークンエンドポイントがシークレットなしで PKCE を受け付けます。パブリッククライアントに発行されたトークンは client_credentials グラントを使えません。

インストールコンテキスト

インストールタブにある、互いに独立した 2 つのチェックボックスです。

ユーザーインストール: ボットは呼び出したユーザーのアカウントにインストールされ、そのユーザーがいるどのチャンネルでもコマンドを使えます。
サーバーインストール: ボットはサーバーにインストールされ、そのサーバー内でのみコマンドを使えます。

少なくとも 1 つは有効にする必要があります。確認画面は有効なものに応じて分岐し、両方が有効ならユーザーが選び、片方だけならピッカーは表示されません。

ワイヤーフォーマットについて: 「サーバーインストール」のカラム名は Discord とバイト単位で同一にするため install_guild_install です。ポータルの UI で「サーバー」と表記しているのは、GameVox がギルドではなくサーバーと呼ぶためです。

既定のインストール設定

有効にした各コンテキストについて、確認画面であらかじめ選択されるスコープと（サーバーインストールでは）権限ビットフィールドを設定します。ユーザーは確認画面でスコープをさらに絞れます。

スコープ: 1 コンテキストにつき最大 25 個。使用可能な文字は [a-z0-9._-]。重複は黙って取り除かれます。
権限（サーバーインストールのみ）: 10 進の文字列、最大 32 文字。Discord の権限整数と同じです。

よく使う既定値:

User install   → ["applications.commands"]
Server install → ["bot", "applications.commands"], perms="0"

インストールリンクのモード

ドロップダウンで、ディレクトリ掲載のインストールボタンの動作を選びます。

なし: インストールボタンを表示しません。インストールは自分で別途対応します。
GameVox 提供: 既定のインストール設定から URL を生成します。実際の URL はポータルのすぐ下に表示されます。
カスタム URL: 完全な https:// の URL を指定します（ユーザーごとの state を発行する独自のインストールゲートウェイなど）。

GameVox 提供 URL の形式

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={URL エンコードし、スペースで連結したスコープ}
  &integration_type={0=サーバー, 1=ユーザー}
  &response_type=code

両方のコンテキストが有効な場合、リンクは integration_type を省略し、確認画面にピッカーが表示されます。

公開鍵と HTTP モードのインタラクション

すべてのアプリに 32 バイトの Ed25519 公開鍵が発行され、基本情報タブに読み取り専用で表示されます。アプリケーション設定でインタラクションのエンドポイント URL を指定すると、GameVox が対応する秘密鍵で署名したインタラクションのペイロードをそこへ POST します。公開鍵を自動で読み込むライブラリ（discord-interactions など）は、追加の設定なしで署名を検証できます。

エンドポイントが設定され 2xx を返す場合、インタラクションは HTTP のみで配信され、ゲートウェイには何も流れません。
エンドポイントに到達できない、または 2xx 以外を返す場合、GameVox はボットのゲートウェイセッション経由での配信にフォールバックします。
署名方式、ヘッダー名、PING への応答は Discord とバイト単位で一致します。
セルフホストサーバーはまだインタラクションを転送しません。HTTP モードの配信が動くのは、現時点ではクラウド上のギルドのインタラクションだけです。

スコープ（現在対応しているもの）

スコープ	効果
`identify`	ユーザーの id、ユーザー名、アバターを読み取ります。
`email`	ユーザーの確認済みメインメールアドレスを読み取ります。
`guilds`	ユーザーのサーバー一覧（id、名前、アイコン、オーナーフラグ、権限）を読み取ります。
`guilds.join`	`PUT /guilds/{id}/members/{user_id}` でユーザーをサーバーに参加させます。
`bot`	サーバーにボットユーザーを追加するサーバーインストールに必要です。
`applications.commands`	インストール先のスコープで、スラッシュ / ユーザー / メッセージコマンドを登録できます。
`messages.read`	予約済み。現時点ではワイヤー上で拒否されます。

Discord との違い

Premium Apps / エンタイトルメントはありません。コマンド権限のエンドポイントとして提供しているのは applications.commands.permissions.update だけです。
トークンに「チーム管理」という考え方はありません。チーム所有のアプリでも、OAuth トークンはアプリケーションに属し、特定のチームメンバーには属しません。
アプリテスター（チームタブ）は、非公開アプリの確認画面で公開／非公開のゲートを回避できます。テスター一覧にいるユーザーは非公開アプリをインストールでき、それ以外のユーザーには「見つかりません」のページが表示されます。

← ドキュメントに戻る