OAuth2 + Installationslinks

Der OAuth2-Ablauf von GameVox ist wire-kompatibel mit dem von Discord. Autorisierungs-URL, Token-Austausch und Scope-Namen stimmen überein; GameVox unterstützt nur den Authorization-Code- und den Refresh-Token-Grant. Diese Seite behandelt die wenigen Felder, die bestimmen, wie sich dein Installationslink verhält und wie der Bestätigungsbildschirm aussieht.

Du willst Personen ohne Bot bei deiner eigenen Website oder App anmelden? Siehe Mit GameVox anmelden.

Endpunkte

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

Eine Serverinstallation braucht nur die Autorisierungs-URL: Die Person wählt einen Server, und der Bot wird hinzugefügt, ohne dass ein Code ausgetauscht werden muss. Die Token-Endpunkte sind für Mit GameVox anmelden da.

Client-Zugangsdaten

Jede Anwendung erhält eine Client-ID (die Anwendungs-Snowflake) und ein Client-Secret. Das Secret wird einmalig beim Erstellen der App und einmal beim Rotieren angezeigt; wir speichern nur den bcrypt-Hash sowie Präfix und die letzten 4 Zeichen.

Rotieren: POST /developer-portal/applications/{id}/reset-secret. Macht das vorherige Secret sofort ungültig.
Verwendung: Mit dem Secret authentifiziert sich dein Server am Token-Endpunkt für Mit GameVox anmelden. Es gibt keine öffentlichen Clients und keinen client_credentials-Grant: Jede Token-Anfrage braucht das Secret, mit oder ohne PKCE.

Installationskontexte

Zwei voneinander unabhängige Kontrollkästchen im Tab „Installation“:

Nutzerinstallation: noch nicht verfügbar. Die Einstellung wird gespeichert, aber Installationslinks mit integration_type=1 und ohne bot-Scope werden auf dem Zustimmungsbildschirm abgelehnt, bis Nutzerinstallationen verfügbar sind.
Serverinstallation: Der Bot wird auf einem Server installiert; Befehle sind nur dort nutzbar.

Mindestens eines muss aktiviert sein. Der Bestätigungsbildschirm richtet sich danach: Sind beide aktiv, wählt die Person aus; ist nur eines aktiv, wird die Auswahl ausgeblendet.

Hinweis zum Wire-Format: Die Spalte für „Serverinstallation“ heißt install_guild_install, um byte-identisch zu Discord zu bleiben. Die Portal-Oberfläche sagt „Server“, weil GameVox sie Server nennt, nicht Guilds.

Standard-Installationseinstellungen

Für jeden aktivierten Kontext konfigurierst du die Scopes und (bei Serverinstallation) das Berechtigungs-Bitfeld, das der Bestätigungsbildschirm vorauswählt. Die Person kann die Scopes dort weiterhin einschränken.

Scopes: maximal 25 pro Kontext. Zeichensatz [a-z0-9._-]. Duplikate werden stillschweigend entfernt.
Berechtigungen (nur Serverinstallation): Dezimalstring, maximal 32 Zeichen. Entspricht Discords Berechtigungs-Integer.

Übliche Standardwerte:

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

Modus des Installationslinks

Das Auswahlfeld bestimmt, wohin der Installieren-Button in deinem Verzeichniseintrag führt:

Keiner: kein Installationsbutton; du regelst die Installation selbst außerhalb.
Von GameVox bereitgestellt: Wir bauen die URL aus deinen Standard-Installationseinstellungen. Das Portal zeigt die effektive URL darunter an.
Eigene URL: Du gibst eine vollständige https://-URL an (z. B. dein eigenes Installations-Gateway, das pro Person einen State ausgibt).

Form der von GameVox bereitgestellten URL

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={URL-kodierte, leerzeichengetrennte Scopes}
  &integration_type={0=Server, 1=Nutzer}
  &response_type=code

Wenn beide Kontexte aktiviert sind, lässt der Link integration_type weg und der Bestätigungsbildschirm zeigt die Auswahl.

Öffentlicher Schlüssel + Interaktionen im HTTP-Modus

Jede App erhält einen 32-Byte-Ed25519-Schlüssel, schreibgeschützt im Tab „Allgemeine Informationen“ sichtbar. Setze deine Endpunkt-URL für Interaktionen in den Anwendungseinstellungen, und GameVox sendet Interaktions-Payloads per POST dorthin, signiert mit dem zugehörigen privaten Schlüssel. Bibliotheken, die den öffentlichen Schlüssel automatisch laden (discord-interactions und ähnliche), prüfen Signaturen ohne weitere Konfiguration.

Ist der Endpunkt konfiguriert und antwortet mit 2xx, wird die Interaktion nur per HTTP zugestellt; über das Gateway geht nichts.
Ist der Endpunkt nicht erreichbar oder antwortet er nicht mit 2xx, fällt GameVox darauf zurück, die Interaktion über die Gateway-Sitzung deines Bots auszuliefern.
Signaturverfahren, Header-Namen und PING-Bestätigung entsprechen Discord Byte für Byte.
Interaktionen auf selbst gehosteten Servern werden genauso zugestellt wie auf Cloud-Servern.
Halte trotzdem eine Gateway-Sitzung verbunden. GameVox reicht jede Interaktion über sie an deine App weiter, bevor es sie per POST an deinen Endpunkt sendet. Ohne verbundene Sitzung wird nichts zugestellt.
Der Antwort-Body wird ignoriert, außer beim PING, den der Button Endpunkt anpingen sendet. Beantworte jede Interaktion mit einem Aufruf von POST /interactions/{id}/{token}/callback.

Scopes

Scope	Wirkung
`bot`	Erforderlich für Serverinstallationen, die einen Bot-Benutzer im Server anlegen.
`applications.commands`	Erlaubt der App, Slash-, Nutzer- und Nachrichtenbefehle im Installationsbereich zu registrieren.
`identify, email, guilds, role_connections.write`	Scopes für die Nutzeranmeldung, ohne `bot` verwendet. Siehe Mit GameVox anmelden.

Unterschiede zu Discord

Keine Premium-Apps / Entitlements; applications.commands.permissions.update ist der einzige Endpunkt für Befehlsberechtigungen, den wir ausliefern.
Keine „teamverwaltete“ Identität für Tokens. Auch bei teameigenen Apps gehören OAuth-Tokens der Anwendung, nicht einem einzelnen Teammitglied.
App-Tester (Tab „Teams“) umgehen bei privaten Apps die Öffentlich/Privat-Sperre auf dem Bestätigungsbildschirm. Personen auf der Testerliste können eine private App installieren; alle anderen erhalten eine Nicht-gefunden-Seite.

← Zurück zur Doku