OAuth2 + URL d’installation

Le parcours OAuth2 de GameVox est compatible au niveau du transport avec celui de Discord. URL d’autorisation, échange de jetons et noms de scopes correspondent ; GameVox ne prend en charge que l’octroi par code d’autorisation et l’octroi par jeton de rafraîchissement. Cette page couvre le petit ensemble de champs qui déterminent le comportement de votre lien d’installation et l’affichage de l’écran de confirmation.

Vous voulez connecter des gens à votre propre site web ou app, sans bot ? Consultez Se connecter avec 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

Une installation serveur n’a besoin que de l’URL d’autorisation : la personne choisit un serveur et le bot y est ajouté, sans code à échanger. Les endpoints de jeton servent à Se connecter avec GameVox.

Identifiants client

Chaque application reçoit un ID client (la snowflake de l’application) et un secret client. Le secret est affiché une seule fois à la création et une fois à chaque rotation ; nous ne conservons que le hash bcrypt, le préfixe et les 4 derniers caractères.

Rotation : POST /developer-portal/applications/{id}/reset-secret. Invalide immédiatement le secret précédent.
Utilisation : le secret authentifie votre serveur auprès de l’endpoint de jeton pour Se connecter avec GameVox. Il n’existe ni clients publics ni octroi client_credentials : chaque requête de jeton exige le secret, avec ou sans PKCE.

Contextes d’installation

Deux cases à cocher dans l’onglet Installation, indépendantes l’une de l’autre :

Installation utilisateur : pas encore disponible. Le réglage s’enregistre, mais les liens d’installation avec integration_type=1 et sans scope bot sont refusés sur l’écran de consentement tant que les installations utilisateur ne sont pas lancées.
Installation serveur : le bot s’installe sur un serveur ; les commandes n’y sont utilisables que là.

Au moins un doit être activé. L’écran de confirmation s’adapte : si les deux sont actifs, la personne choisit ; si un seul l’est, le sélecteur est masqué.

Note sur le format de transport : la colonne de « l’installation serveur » s’appelle install_guild_install pour rester identique octet pour octet à Discord. L’interface du portail dit « Serveur » parce que GameVox les appelle serveurs, pas guilds.

Réglages d’installation par défaut

Pour chaque contexte activé, vous configurez les scopes et (pour l’installation serveur) le champ de bits de permissions que l’écran de confirmation présélectionne. La personne peut toujours réduire les scopes sur cet écran.

Scopes : 25 au maximum par contexte. Jeu de caractères [a-z0-9._-]. Les doublons sont supprimés en silence.
Permissions (installation serveur uniquement) : chaîne décimale, 32 caractères maximum. Correspond à l’entier de permissions de Discord.

Valeurs par défaut courantes :

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

Mode du lien d’installation

La liste déroulante détermine ce que fait le bouton Installer de votre fiche d’annuaire :

Aucun : pas de bouton d’installation ; vous gérez l’installation de votre côté.
Fourni par GameVox : nous construisons l’URL à partir de vos réglages d’installation par défaut. Le portail affiche l’URL effective en dessous.
URL personnalisée : vous fournissez une URL https:// complète (par exemple votre propre passerelle d’installation qui émet un state par personne).

Forme de l’URL fournie par GameVox

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={scopes encodés en URL et joints par des espaces}
  &integration_type={0=serveur, 1=utilisateur}
  &response_type=code

Quand les deux contextes sont activés, le lien omet integration_type et l’écran de confirmation affiche le sélecteur.

Clé publique + interactions en mode HTTP

Chaque app reçoit une clé publique Ed25519 de 32 octets, affichée en lecture seule dans l’onglet Informations générales. Définissez votre URL d’endpoint d’interactions dans les réglages de l’application et GameVox y enverra les charges d’interaction en POST, signées avec la clé privée correspondante. Les bibliothèques qui chargent automatiquement la clé publique (discord-interactions et consorts) vérifient les signatures sans configuration supplémentaire.

Si l’endpoint est configuré et renvoie 2xx, l’interaction n’est livrée que par HTTP ; rien ne passe par le gateway.
Si l’endpoint est injoignable ou renvoie autre chose qu’un 2xx, GameVox se rabat sur l’envoi de l’interaction via la session gateway de votre bot.
Le schéma de signature, les noms d’en-tête et l’accusé PING correspondent octet pour octet à Discord.
Les interactions sur les serveurs auto-hébergés sont délivrées de la même façon que sur les serveurs cloud.
Gardez quand même une session gateway connectée. GameVox transmet chaque interaction à votre app par cette session avant de l’envoyer en POST à votre endpoint ; sans session connectée, rien n’est délivré.
Le corps de la réponse est ignoré, sauf pour le PING envoyé par le bouton Tester l’endpoint. Répondez à chaque interaction en appelant POST /interactions/{id}/{token}/callback.

Scopes

Scope	Effet
`bot`	Nécessaire pour les installations serveur qui y créent un utilisateur bot.
`applications.commands`	Permet à l’app d’enregistrer des commandes slash, utilisateur et message dans le périmètre d’installation.
`identify, email, guilds, role_connections.write`	Scopes de connexion utilisateur, utilisés sans `bot`. Consultez Se connecter avec GameVox.

Différences avec Discord

Pas de Premium Apps ni d’entitlements ; applications.commands.permissions.update est le seul endpoint de permissions de commandes que nous fournissons.
Pas d’identité « gérée par équipe » pour les jetons. Même sur les apps d’équipe, les jetons OAuth appartiennent à l’application, pas à un membre en particulier.
Les testeurs d’app (onglet Équipes) contournent la barrière public/privé sur l’écran de confirmation pour les apps privées. Les personnes inscrites sur la liste des testeurs peuvent installer une app privée ; les autres obtiennent une page introuvable.

← Retour à la documentation