OAuth2 + adresy URL instalacji

Przepływ OAuth2 w GameVox jest zgodny z Discordem na poziomie protokołu. URL autoryzacji, wymiana tokenów i nazwy zakresów są takie same; GameVox obsługuje tylko granty authorization code i refresh token. Ta strona opisuje niewielki zestaw pól, które decydują o działaniu linku instalacyjnego i wyglądzie ekranu potwierdzenia instalacji.

Chcesz logować użytkowników do własnej witryny lub aplikacji, bez żadnego bota? Zobacz Logowanie przez GameVox.

Endpointy

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

Instalacja na serwerze wymaga tylko URL autoryzacji: użytkownik wybiera serwer i bot zostaje dodany, bez wymiany żadnego kodu. Endpointy tokenów służą do logowania przez GameVox.

Dane uwierzytelniające klienta

Każda aplikacja dostaje client ID (snowflake aplikacji) i client secret. Sekret jest pokazywany raz przy tworzeniu aplikacji i raz przy rotacji; przechowujemy tylko hash bcrypt oraz prefiks i ostatnie 4 znaki.

Rotacja: POST /developer-portal/applications/{id}/reset-secret. Poprzedni sekret natychmiast przestaje działać.
Zastosowanie: sekret uwierzytelnia twój serwer na endpoincie tokenów przy logowaniu przez GameVox. Nie ma klientów publicznych ani grantu client_credentials: każde żądanie tokena wymaga sekretu, z PKCE lub bez.

Konteksty instalacji

Dwa pola wyboru w zakładce Instalacja, niezależne od siebie:

Instalacja dla użytkownika: jeszcze niedostępna. Ustawienie się zapisuje, ale linki instalacyjne z integration_type=1 i bez zakresu bot są odrzucane na ekranie zgody, dopóki instalacje dla użytkownika nie zostaną udostępnione.
Instalacja na serwerze: bot instaluje się na serwerze; komend można używać tylko na tym serwerze.

Przynajmniej jeden kontekst musi być włączony. Ekran potwierdzenia instalacji zależy od tego, co jest dostępne: jeśli włączone są oba, użytkownik wybiera; jeśli jeden, selektor jest ukryty.

Uwaga dotycząca formatu danych: kolumna dla „instalacji na serwerze” nazywa się install_guild_install, żeby zachować identyczność bajt w bajt z Discordem. Interfejs portalu mówi „Serwer”, bo GameVox nazywa je serwerami, a nie gildiami.

Domyślne ustawienia instalacji

Dla każdego włączonego kontekstu konfigurujesz zakresy oraz (dla instalacji na serwerze) pole bitowe uprawnień, które ekran potwierdzenia instalacji zaznacza domyślnie. Użytkownik nadal może zawęzić zakresy na ekranie potwierdzenia.

Zakresy: maksymalnie 25 na kontekst. Dozwolone znaki [a-z0-9._-]. Duplikaty są po cichu usuwane.
Uprawnienia (tylko instalacja na serwerze): ciąg dziesiętny, maksymalnie 32 znaki. Odpowiada liczbie uprawnień Discorda.

Typowe wartości domyślne:

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

Tryb linku instalacyjnego

Lista rozwijana określa, dokąd prowadzi przycisk Zainstaluj w twoim wpisie w katalogu:

Brak: bez przycisku instalacji; instalację obsługujesz samodzielnie, poza portalem.
Dostarczony przez GameVox: budujemy URL na podstawie twoich domyślnych ustawień instalacji. Portal pokazuje pod spodem wynikowy URL.
Własny URL: podajesz pełny URL https:// (np. własną bramkę instalacyjną, która wydaje stan dla każdego użytkownika).

Postać URL dostarczanego przez GameVox

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={zakresy rozdzielone spacjami, zakodowane w URL}
  &integration_type={0=serwer, 1=użytkownik}
  &response_type=code

Gdy włączone są oba konteksty, link pomija integration_type, a ekran potwierdzenia wyświetla selektor.

Klucz publiczny + interakcje w trybie HTTP

Każda aplikacja dostaje 32-bajtowy klucz publiczny Ed25519, wyświetlany tylko do odczytu w zakładce Informacje ogólne. Ustaw Interactions Endpoint URL w ustawieniach aplikacji, a GameVox będzie wysyłać tam metodą POST payloady interakcji podpisane odpowiadającym kluczem prywatnym. Biblioteki, które automatycznie wczytują klucz publiczny (discord-interactions i podobne), weryfikują podpisy bez dodatkowej konfiguracji.

Jeśli endpoint jest skonfigurowany i zwraca 2xx, interakcja jest dostarczana wyłącznie przez HTTP; nic nie idzie przez gateway.
Jeśli endpoint jest nieosiągalny lub zwraca kod inny niż 2xx, GameVox awaryjnie wysyła interakcję przez sesję gatewaya twojego bota.
Schemat podpisu, nazwy nagłówków i potwierdzanie PING są zgodne z Discordem co do bajtu.
Interakcje na serwerach hostowanych samodzielnie są dostarczane tak samo jak na serwerach w chmurze.
Mimo to utrzymuj połączoną sesję gateway. GameVox przekazuje każdą interakcję twojej aplikacji przez tę sesję, zanim wyśle ją metodą POST na twój endpoint, więc bez połączonej sesji nic nie zostanie dostarczone.
Treść odpowiedzi jest ignorowana, poza PING wysyłanym przez przycisk Pinguj endpoint. Odpowiadaj na każdą interakcję, wywołując POST /interactions/{id}/{token}/callback.

Zakresy

Zakres	Działanie
`bot`	Wymagany przy instalacjach na serwerze, które dodają do serwera użytkownika bota.
`applications.commands`	Pozwala aplikacji rejestrować komendy ukośnikowe, użytkownika i wiadomości w zakresie instalacji.
`identify, email, guilds, role_connections.write`	Zakresy logowania użytkowników, używane bez `bot`. Zobacz Logowanie przez GameVox.

Różnice względem Discorda

Brak Premium Apps i uprawnień zakupowych (entitlements); applications.commands.permissions.update to jedyny endpoint uprawnień komend, jaki udostępniamy.
Brak tożsamości „zarządzanej przez zespół” dla tokenów. Nawet w aplikacjach należących do zespołu tokeny OAuth należą do aplikacji, a nie do konkretnego członka zespołu.
Testerzy aplikacji (zakładka Zespoły) omijają blokadę publiczna/prywatna na ekranie potwierdzenia instalacji aplikacji prywatnych. Użytkownicy z listy testerów mogą zainstalować prywatną aplikację; wszyscy pozostali widzą stronę „nie znaleziono”.

← Powrót do dokumentacji