OAuth2 + インストール URL

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

ボットなしで、自分のウェブサイトやアプリにユーザーをサインインさせたい場合は、GameVox でログインを参照してください。

エンドポイント

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

サーバーインストールに必要なのは認可 URL だけです。ユーザーがサーバーを選ぶとボットが追加され、交換するコードはありません。トークンエンドポイントは GameVox でログインのためのものです。

クライアント認証情報

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

ローテーション: POST /developer-portal/applications/{id}/reset-secret。以前のシークレットは直ちに無効になります。
用途: シークレットは、GameVox でログインのトークンエンドポイントであなたのサーバーを認証するために使います。パブリッククライアントも client_credentials グラントもありません。PKCE の有無にかかわらず、すべてのトークンリクエストにシークレットが必要です。

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

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

ユーザーインストール: まだ利用できません。設定は保存されますが、integration_type=1 で bot スコープを含まないインストールリンクは、ユーザーインストールが提供されるまで同意画面で拒否されます。
サーバーインストール: ボットはサーバーにインストールされ、そのサーバー内でのみコマンドを使えます。

少なくとも 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 とバイト単位で一致します。
セルフホストサーバーのインタラクションも、クラウドサーバーと同じ方法で配信されます。
それでもゲートウェイのセッションは接続したままにしてください。GameVox は各インタラクションをこのセッション経由でアプリに渡してから、エンドポイントへ POST します。そのため、接続中のセッションがなければ何も配信されません。
レスポンスのボディは無視されます（エンドポイントに ping ボタンが送る PING を除く）。各インタラクションには POST /interactions/{id}/{token}/callback を呼び出して応答してください。

スコープ

スコープ	効果
`bot`	サーバーにボットユーザーを追加するサーバーインストールに必要です。
`applications.commands`	インストール先のスコープで、スラッシュ / ユーザー / メッセージコマンドを登録できます。
`identify, email, guilds, role_connections.write`	ユーザーのサインイン用のスコープで、`bot` なしで使います。GameVox でログインを参照してください。

Discord との違い

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

← ドキュメントに戻る