OAuth2 + Installationslinks

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

Endpunkte

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

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.
Öffentliche Clients (Mobil-Apps, SPAs): Aktiviere Öffentlicher Client. Der Token-Endpunkt akzeptiert dann PKCE ohne Secret. An öffentliche Clients ausgegebene Tokens können den client_credentials-Grant nicht nutzen.

Installationskontexte

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

Nutzerinstallation: Der Bot wird im Konto der aufrufenden Person installiert; Befehle sind in jedem Kanal nutzbar, in dem sie sich befindet.
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.
Selbst gehostete Server leiten Interaktionen noch nicht weiter; die Zustellung im HTTP-Modus greift heute nur für Guild-Interaktionen in der Cloud.

Scopes (derzeit berücksichtigt)

Scope	Wirkung
`identify`	Liest ID, Benutzernamen und Avatar der Person.
`email`	Liest die bestätigte primäre E-Mail-Adresse der Person.
`guilds`	Liest die Serverliste der Person (ID, Name, Symbol, Eigentümer-Flag, Berechtigungen).
`guilds.join`	Fügt die Person über `PUT /guilds/{id}/members/{user_id}` einem Server hinzu.
`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.
`messages.read`	Reserviert; wird derzeit auf dem Wire abgelehnt.

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