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 e nomes de scope coincidem; o GameVox suporta apenas as concessões por código de autorização e por refresh token. 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.

Quer que as pessoas entrem no seu próprio site ou app, sem bot? Veja Entrar com o 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

Uma instalação em servidor só precisa da URL de autorização: a pessoa escolhe um servidor e o bot é adicionado, sem nenhum código para trocar. Os endpoints de token servem ao Entrar com o GameVox.

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.
Uso: o segredo autentica o seu servidor no endpoint de token do Entrar com o GameVox. Não existem clientes públicos nem a concessão client_credentials: toda requisição de token precisa do segredo, com ou sem PKCE.

Contextos de instalação

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

Instalação em conta: ainda não disponível. A configuração é salva, mas links de instalação com integration_type=1 e sem o scope bot são recusados na tela de consentimento até que as instalações em conta sejam lançadas.
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.
Interações em servidores auto-hospedados são entregues da mesma forma que em servidores na nuvem.
Mantenha uma sessão de gateway conectada mesmo assim. O GameVox entrega cada interação ao seu app por meio dela antes de enviá-la por POST ao seu endpoint, então sem uma sessão conectada nada é entregue.
O corpo da resposta é ignorado, exceto no PING enviado pelo botão Testar endpoint. Responda a cada interação chamando POST /interactions/{id}/{token}/callback.

Scopes

Scope	Efeito
`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.
`identify, email, guilds, role_connections.write`	Scopes de login de usuário, usados sem `bot`. Veja Entrar com o GameVox.

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