OAuth2 + Install URLs

GameVox's OAuth2 flow is wire-compatible with Discord's. Authorize URL, token exchange, scope names, and grant types all match. This page covers the small set of fields that drive how your install link behaves and how the install confirm screen renders.

Endpoints

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

Client credentials

Every application gets a client ID (the application snowflake) and a client secret. The secret is shown once on app create and once on rotate; we store only the bcrypt hash plus prefix + last4.

Rotate: POST /developer-portal/applications/{id}/reset-secret — invalidates the previous secret immediately.
Public clients (mobile apps, SPAs): toggle Public Client on. The token endpoint accepts PKCE without a secret. Tokens issued to public clients cannot use the client_credentials grant.

Install contexts

Two checkboxes on the Installation tab, independent of each other:

User install — bot installs to the invoking user's account; commands are usable in any channel they're in.
Server install — bot installs to a server; commands are usable in that server only.

At least one must be enabled. The install confirm screen branches on what's available: if both are on, the user picks; if one is on, the picker is hidden.

Wire-format note: the column for "server install" is named install_guild_install to stay byte-identical with Discord. The portal UI says "Server" because GameVox calls them servers, not guilds.

Default install settings

For each enabled context you configure the scopes and (for server install) the permission bitfield that the install confirm screen pre-selects. The user can still narrow scopes on the confirm screen.

Scopes: max 25 per context. Charset [a-z0-9._-]. Duplicates are silently de-duped.
Permissions (server install only): decimal string, max 32 chars. Matches Discord's permission integer.

Common defaults:

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

Install link mode

The dropdown picks how the Install button on your directory listing resolves:

None — no install button; you handle install yourself out-of-band.
GameVox-provided — we build the URL from your default install settings. The portal shows the effective URL underneath.
Custom URL — you provide a fully-qualified https:// URL (e.g., your own install gateway that issues per-user state).

GameVox-provided URL shape

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={url-encoded space-joined scopes}
  &integration_type={0=server, 1=user}
  &response_type=code

When both contexts are enabled, the link omits integration_type and the confirm screen renders the picker.

Public key

Every app gets a 32-byte Ed25519 public key, displayed read-only on the General Information tab. v1 of the portal exposes the field for HTTP-mode interaction signature verification — the field is in place so libraries that auto-load it (discord-interactions and friends) don't error. HTTP-mode interactions themselves are not yet wired; configure your interactions endpoint URL and we'll start signing when it lands.

Scopes (currently honored)

Scope	Effect
`identify`	Read user's id, username, avatar.
`email`	Read user's verified primary email.
`guilds`	Read user's server list (id, name, icon, owner flag, perms).
`guilds.join`	Join the user to a server via `PUT /guilds/{id}/members/{user_id}`.
`bot`	Required for server installs that drop a bot user into the server.
`applications.commands`	Lets the app register slash / user / message commands in the install scope.
`messages.read`	Reserved; rejected on the wire today.

Differences from Discord

No Premium Apps / entitlements; applications.commands.permissions.update is the only commands-permissions endpoint we ship.
No "team-managed" identity for tokens — even on team-owned apps, OAuth tokens belong to the application, not to a specific team member.
App Testers (Teams tab) bypass the public/private gate on the install confirm screen for private apps. Listed users on the testers roster can install a private app; everyone else gets a not-found page.

← Back to docs