← Docs

OAuth2 + Install URLs

GameVox's OAuth2 flow is wire-compatible with Discord's. The authorize URL, token exchange and scope names match; GameVox supports the authorization-code and refresh-token grants only. This page covers the small set of fields that drive how your install link behaves and how the install confirm screen renders.

Signing people in to your own website or app, with no bot? See Log in with GameVox.

Endpoints

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

A server install needs only the authorize URL: the user picks a server and the bot is added, with no code to exchange. The token endpoints serve Log in with GameVox.

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.
• Use: the secret authenticates your server at the token endpoint for Log in with GameVox. There are no public clients and no client_credentials grant: every token request needs the secret, with or without PKCE.

Install contexts

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

• User install: not available yet. The setting saves, but install links with integration_type=1 and no bot scope are refused on the consent screen until user installs ship.
• 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.
• Interactions on self-hosted servers are delivered the same way as on cloud servers.
• Keep a gateway session connected anyway. GameVox hands each interaction to your app through it before POSTing to your endpoint, so with no session connected nothing is delivered.
• The response body is ignored, except for the PING sent by the Ping endpoint button. Answer each interaction by calling POST /interactions/{id}/{token}/callback.

Scopes

Scope	Effect
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.
identify, email, guilds, role_connections.write	User sign-in scopes, used without bot. See Log in with GameVox.

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