OAuth2 + URLs de instalación

El flujo OAuth2 de GameVox es compatible a nivel de cable con el de Discord. La URL de autorización, el intercambio de tokens, los nombres de scope y los tipos de concesión coinciden. Esta página cubre el pequeño conjunto de campos que determinan cómo se comporta tu enlace de instalación y cómo se muestra la pantalla de confirmación.

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

Credenciales de cliente

Cada aplicación obtiene un ID de cliente (la snowflake de la aplicación) y un secreto de cliente. El secreto se muestra una sola vez al crear la app y otra al rotarlo; solo guardamos el hash bcrypt más el prefijo y los últimos 4 caracteres.

Rotar: POST /developer-portal/applications/{id}/reset-secret. Invalida el secreto anterior de inmediato.
Clientes públicos (apps móviles, SPAs): activa Cliente público. El endpoint de token acepta PKCE sin secreto. Los tokens emitidos a clientes públicos no pueden usar la concesión client_credentials.

Contextos de instalación

Dos casillas en la pestaña Instalación, independientes entre sí:

Instalación de usuario: el bot se instala en la cuenta de quien lo invoca; los comandos se pueden usar en cualquier canal donde esté esa persona.
Instalación en servidor: el bot se instala en un servidor; los comandos solo se pueden usar allí.

Debe haber al menos uno activado. La pantalla de confirmación se adapta a lo disponible: si están los dos, la persona elige; si solo hay uno, el selector se oculta.

Nota sobre el formato de cable: la columna de «instalación en servidor» se llama install_guild_install para mantenerse idéntica byte a byte con Discord. La interfaz del portal dice «Servidor» porque GameVox los llama servidores, no guilds.

Ajustes de instalación por defecto

Para cada contexto activado configuras los scopes y (en la instalación en servidor) el campo de bits de permisos que la pantalla de confirmación preselecciona. Quien instale todavía puede reducir los scopes en esa pantalla.

Scopes: máximo 25 por contexto. Juego de caracteres [a-z0-9._-]. Los duplicados se eliminan en silencio.
Permisos (solo instalación en servidor): cadena decimal, máximo 32 caracteres. Coincide con el entero de permisos de Discord.

Valores por defecto habituales:

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

Modo del enlace de instalación

El desplegable determina cómo se resuelve el botón Instalar de tu ficha en el directorio:

Ninguno: sin botón de instalación; gestionas la instalación por tu cuenta.
Proporcionado por GameVox: construimos la URL a partir de tus ajustes de instalación por defecto. El portal muestra debajo la URL efectiva.
URL personalizada: proporcionas una URL https:// completa (por ejemplo, tu propia pasarela de instalación que emite un state por persona).

Forma de la URL proporcionada por GameVox

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={scopes codificados en URL y unidos por espacios}
  &integration_type={0=servidor, 1=usuario}
  &response_type=code

Cuando ambos contextos están activados, el enlace omite integration_type y la pantalla de confirmación muestra el selector.

Clave pública + interacciones en modo HTTP

Cada app obtiene una clave pública Ed25519 de 32 bytes, visible en solo lectura en la pestaña Información general. Define tu URL del endpoint de interacciones en los ajustes de la aplicación y GameVox enviará allí por POST las cargas de interacción, firmadas con la clave privada correspondiente. Las bibliotecas que cargan la clave pública automáticamente (discord-interactions y similares) verifican las firmas sin configuración extra.

Si el endpoint está configurado y devuelve 2xx, la interacción se entrega solo por HTTP; nada va por el gateway.
Si el endpoint no es accesible o devuelve algo distinto de 2xx, GameVox vuelve a entregar la interacción por la sesión de gateway de tu bot.
El esquema de firma, los nombres de cabecera y el acuse de PING coinciden byte a byte con Discord.
Los servidores autoalojados todavía no reenvían interacciones; el modo HTTP solo se dispara hoy para interacciones de guilds en la nube.

Scopes (admitidos actualmente)

Scope	Efecto
`identify`	Lee el id, nombre de usuario y avatar de la persona.
`email`	Lee el correo principal verificado de la persona.
`guilds`	Lee la lista de servidores de la persona (id, nombre, icono, indicador de propiedad, permisos).
`guilds.join`	Añade a la persona a un servidor mediante `PUT /guilds/{id}/members/{user_id}`.
`bot`	Necesario para instalaciones en servidor que colocan un usuario bot en él.
`applications.commands`	Permite a la app registrar comandos de barra, de usuario y de mensaje en el ámbito de la instalación.
`messages.read`	Reservado; hoy se rechaza en el cable.

Diferencias con Discord

Sin Premium Apps ni entitlements; applications.commands.permissions.update es el único endpoint de permisos de comandos que ofrecemos.
Sin identidad «gestionada por equipo» para los tokens. Incluso en apps de equipo, los tokens OAuth pertenecen a la aplicación, no a una persona concreta del equipo.
Los testers de la app (pestaña Equipos) se saltan la barrera público/privado en la pantalla de confirmación para las apps privadas. Quien esté en la lista de testers puede instalar una app privada; el resto obtiene una página de no encontrado.

← Volver a la documentación