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 + HTTP-mode interactions

Every app gets a 32-byte Ed25519 public key, displayed read-only on the General Information tab. Set your Interactions Endpoint URL on the application settings and GameVox will POST interaction payloads there signed with the corresponding private key. Libraries that auto-load the public key (discord-interactions and friends) verify signatures without any extra config.

If the endpoint is configured and returns 2xx, the interaction is delivered over HTTP only; nothing goes over the gateway.
If the endpoint is unreachable or returns non-2xx, GameVox falls back to dispatching the interaction over your bot's gateway session.
Signature scheme, header names, and PING acknowledgment match Discord byte-for-byte.
Self-hosted servers do not yet forward interactions; HTTP-mode dispatch fires only for cloud-hosted guild interactions today.

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