← Documentação

OAuth2 + URLs de instalação

O fluxo OAuth2 do GameVox é compatível no transporte com o do Discord. URL de autorização, troca de token, nomes de scope e tipos de concessão coincidem. Esta página cobre o pequeno conjunto de campos que definem como o seu link de instalação se comporta e como a tela de confirmação aparece.

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

Credenciais de cliente

Toda aplicação recebe um ID de cliente (a snowflake da aplicação) e um segredo de cliente. O segredo aparece uma vez na criação e uma vez a cada rotação; guardamos apenas o hash bcrypt, o prefixo e os 4 últimos caracteres.

• Rotacionar: POST /developer-portal/applications/{id}/reset-secret. Invalida o segredo anterior na hora.
• Clientes públicos (apps móveis, SPAs): ative Cliente público. O endpoint de token aceita PKCE sem segredo. Tokens emitidos para clientes públicos não podem usar a concessão client_credentials.

Contextos de instalação

Duas caixas de seleção na aba Instalação, independentes entre si:

• Instalação em conta: o bot é instalado na conta de quem chamou; os comandos podem ser usados em qualquer canal onde essa pessoa esteja.
• Instalação em servidor: o bot é instalado em um servidor; os comandos só podem ser usados ali.

Pelo menos um precisa estar ativo. A tela de confirmação se adapta: se os dois estiverem ativos, a pessoa escolhe; se só um estiver, o seletor fica oculto.

Nota sobre o transporte: a coluna da “instalação em servidor” se chama install_guild_install para permanecer idêntica byte a byte ao Discord. A interface do portal diz “Servidor” porque o GameVox os chama de servidores, não de guilds.

Configurações de instalação padrão

Para cada contexto ativo você configura os scopes e (na instalação em servidor) o campo de bits de permissões que a tela de confirmação pré-seleciona. A pessoa ainda pode reduzir os scopes nessa tela.

• Scopes: no máximo 25 por contexto. Conjunto de caracteres [a-z0-9._-]. Duplicatas são removidas em silêncio.
• Permissões (só instalação em servidor): string decimal, no máximo 32 caracteres. Igual ao inteiro de permissões do Discord.

Padrões comuns:

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

Modo do link de instalação

A lista suspensa define para onde o botão Instalar do seu anúncio no diretório leva:

• Nenhum: sem botão de instalação; você cuida da instalação por fora.
• Fornecido pelo GameVox: montamos a URL a partir das suas configurações de instalação padrão. O portal mostra a URL efetiva logo abaixo.
• URL personalizada: você informa uma URL https:// completa (por exemplo, seu próprio gateway de instalação que emite um state por pessoa).

Formato da URL fornecida pelo GameVox

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={scopes codificados em URL, unidos por espaços}
  &integration_type={0=servidor, 1=conta}
  &response_type=code

Quando os dois contextos estão ativos, o link omite integration_type e a tela de confirmação mostra o seletor.

Chave pública + interações em modo HTTP

Cada app recebe uma chave pública Ed25519 de 32 bytes, exibida em modo leitura na aba Informações gerais. Defina a sua URL do endpoint de interações nas configurações da aplicação e o GameVox enviará os payloads de interação por POST para lá, assinados com a chave privada correspondente. Bibliotecas que carregam a chave pública automaticamente (discord-interactions e afins) verificam as assinaturas sem configuração extra.

• Se o endpoint estiver configurado e responder 2xx, a interação é entregue só por HTTP; nada vai pelo gateway.
• Se o endpoint estiver inacessível ou responder algo que não seja 2xx, o GameVox volta a entregar a interação pela sessão de gateway do seu bot.
• O esquema de assinatura, os nomes de cabeçalho e a confirmação de PING batem byte a byte com o Discord.
• Servidores auto-hospedados ainda não encaminham interações; o modo HTTP só dispara hoje para interações de guilds na nuvem.

Scopes (atualmente honrados)

Scope	Efeito
identify	Lê o id, o nome de usuário e o avatar da pessoa.
email	Lê o e-mail principal verificado da pessoa.
guilds	Lê a lista de servidores da pessoa (id, nome, ícone, indicador de propriedade, permissões).
guilds.join	Adiciona a pessoa a um servidor via PUT /guilds/{id}/members/{user_id}.
bot	Necessário para instalações em servidor que criam um usuário bot nele.
applications.commands	Permite ao app registrar comandos de barra, de usuário e de mensagem no escopo da instalação.
messages.read	Reservado; recusado no transporte hoje.

Diferenças em relação ao Discord

• Sem Premium Apps nem entitlements; applications.commands.permissions.update é o único endpoint de permissões de comando que oferecemos.
• Sem identidade “gerenciada por equipe” para tokens. Mesmo em apps de equipe, os tokens OAuth pertencem à aplicação, não a uma pessoa específica.
• Os testadores do app (aba Equipes) passam pela barreira público/privado na tela de confirmação em apps privados. Quem está na lista de testadores pode instalar um app privado; o resto recebe uma página de não encontrado.

← Voltar para a documentação