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, noms de scopes et types d’octroi correspondent. 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.

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

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.
Clients publics (apps mobiles, SPA) : activez Client public. L’endpoint de jeton accepte alors PKCE sans secret. Les jetons délivrés à des clients publics ne peuvent pas utiliser l’octroi client_credentials.

Contextes d’installation

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

Installation utilisateur : le bot s’installe sur le compte de la personne ; les commandes sont utilisables dans tous les salons où elle se trouve.
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 serveurs auto-hébergés ne relaient pas encore les interactions ; le mode HTTP ne se déclenche aujourd’hui que pour les interactions de guilds hébergées dans le cloud.

Scopes (actuellement honorés)

Scope	Effet
`identify`	Lit l’id, le nom d’utilisateur et l’avatar de la personne.
`email`	Lit l’adresse e-mail principale vérifiée de la personne.
`guilds`	Lit la liste des serveurs de la personne (id, nom, icône, indicateur de propriété, permissions).
`guilds.join`	Ajoute la personne à un serveur via `PUT /guilds/{id}/members/{user_id}`.
`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.
`messages.read`	Réservé ; refusé sur le canal aujourd’hui.

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