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 y los nombres de scope coinciden; GameVox solo admite las concesiones de código de autorización y de token de actualización. 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.

¿Quieres que las personas inicien sesión en tu propio sitio web o app, sin bot? Consulta Iniciar sesión con 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

Una instalación en servidor solo necesita la URL de autorización: la persona elige un servidor y se añade el bot, sin ningún código que intercambiar. Los endpoints de token son para Iniciar sesión con GameVox.

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.
Uso: el secreto autentica a tu servidor en el endpoint de token de Iniciar sesión con GameVox. No hay clientes públicos ni concesión client_credentials: toda solicitud de token necesita el secreto, con o sin PKCE.

Contextos de instalación

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

Instalación de usuario: todavía no disponible. El ajuste se guarda, pero los enlaces de instalación con integration_type=1 y sin el scope bot se rechazan en la pantalla de consentimiento hasta que las instalaciones de usuario estén disponibles.
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.
Las interacciones en servidores autoalojados se entregan igual que en los servidores en la nube.
Mantén igualmente una sesión de gateway conectada. GameVox entrega cada interacción a tu app a través de ella antes de enviarla por POST a tu endpoint, así que sin una sesión conectada no se entrega nada.
El cuerpo de la respuesta se ignora, salvo para el PING que envía el botón Hacer ping al endpoint. Responde a cada interacción llamando a POST /interactions/{id}/{token}/callback.

Scopes

Scope	Efecto
`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.
`identify, email, guilds, role_connections.write`	Scopes de inicio de sesión de usuario, usados sin `bot`. Consulta Iniciar sesión con GameVox.

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