OAuth2 + URL установки

Процесс OAuth2 в GameVox совместим с Discord на уровне протокола. URL авторизации, обмен токенов и названия скоупов совпадают; GameVox поддерживает только гранты authorization code и refresh token. На этой странице описан небольшой набор полей, которые определяют поведение вашей ссылки для установки и вид экрана подтверждения установки.

Хотите, чтобы люди входили на ваш сайт или в приложение без всякого бота? См. Вход через GameVox.

Эндпоинты

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

Для установки на сервер нужен только URL авторизации: пользователь выбирает сервер, и бот добавляется, обменивать код не нужно. Эндпоинты токенов служат для входа через GameVox.

Учётные данные клиента

Каждое приложение получает ID клиента (snowflake приложения) и секрет клиента. Секрет показывается один раз при создании приложения и один раз при смене; мы храним только хеш bcrypt, а также префикс и последние 4 символа.

Смена: POST /developer-portal/applications/{id}/reset-secret. Предыдущий секрет сразу становится недействительным.
Использование: секрет аутентифицирует ваш сервер на эндпоинте токенов для входа через GameVox. Публичных клиентов и гранта client_credentials нет: каждому запросу токена нужен секрет, с PKCE или без.

Контексты установки

Два флажка на вкладке «Установка», независимые друг от друга:

Установка пользователю: пока недоступна. Настройка сохраняется, но ссылки установки с integration_type=1 и без скоупа bot отклоняются на экране согласия, пока установки пользователю не появятся.
Установка на сервер: бот устанавливается на сервер; команды доступны только на этом сервере.

Хотя бы один должен быть включён. Экран подтверждения установки зависит от того, что доступно: если включены оба, выбирает пользователь; если один, выбор скрыт.

Примечание о формате данных: столбец для «установки на сервер» называется install_guild_install, чтобы побайтно совпадать с Discord. В интерфейсе портала написано «Сервер», потому что в GameVox это серверы, а не гильдии.

Настройки установки по умолчанию

Для каждого включённого контекста вы задаёте скоупы и (для установки на сервер) битовое поле прав, которые экран подтверждения установки выбирает заранее. Пользователь всё равно может сузить скоупы на экране подтверждения.

Скоупы: не более 25 на контекст. Набор символов [a-z0-9._-]. Дубликаты молча удаляются.
Права (только для установки на сервер): десятичная строка, не более 32 символов. Совпадает с целым числом прав в Discord.

Типичные значения по умолчанию:

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

Режим ссылки для установки

Выпадающий список определяет, куда ведёт кнопка Установить в вашей карточке в каталоге:

Нет: кнопки установки нет; установку вы организуете сами отдельно.
Ссылка от GameVox: мы собираем URL из ваших настроек установки по умолчанию. Итоговый URL портал показывает ниже.
Собственный URL: вы указываете полный URL с https:// (например, свой шлюз установки, который выдаёт состояние для каждого пользователя).

Вид URL от GameVox

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={скоупы через пробел, в URL-кодировке}
  &integration_type={0=сервер, 1=пользователь}
  &response_type=code

Если включены оба контекста, ссылка не содержит integration_type, и экран подтверждения показывает выбор.

Публичный ключ + взаимодействия в режиме HTTP

Каждое приложение получает 32-байтовый публичный ключ Ed25519, который показан только для чтения на вкладке «Общая информация». Укажите URL эндпоинта взаимодействий в настройках приложения, и GameVox будет отправлять туда POST с payload взаимодействий, подписанными соответствующим закрытым ключом. Библиотеки, которые сами загружают публичный ключ (discord-interactions и подобные), проверяют подписи без дополнительной настройки.

Если эндпоинт настроен и возвращает 2xx, взаимодействие доставляется только по HTTP; через шлюз ничего не идёт.
Если эндпоинт недоступен или возвращает не 2xx, GameVox отправляет взаимодействие через сессию шлюза вашего бота.
Схема подписи, названия заголовков и подтверждение PING побайтно совпадают с Discord.
Взаимодействия на собственных серверах доставляются так же, как на облачных.
Всё равно держите сессию шлюза подключённой. GameVox передаёт каждое взаимодействие вашему приложению через неё и только потом отправляет POST на ваш эндпоинт, поэтому без подключённой сессии ничего не доставляется.
Тело ответа игнорируется, кроме PING, который отправляет кнопка Проверить эндпоинт. Отвечайте на каждое взаимодействие вызовом POST /interactions/{id}/{token}/callback.

Скоупы

Скоуп	Действие
`bot`	Нужен для установок на сервер, которые добавляют на сервер пользователя-бота.
`applications.commands`	Позволяет приложению регистрировать слэш-команды, команды пользователя и сообщения в области установки.
`identify, email, guilds, role_connections.write`	Скоупы для входа пользователей, используются без `bot`. См. Вход через GameVox.

Отличия от Discord

Нет Premium Apps и entitlements; applications.commands.permissions.update единственный эндпоинт прав для команд, который у нас есть.
Нет идентичности токенов «под управлением команды». Даже у приложений команд OAuth-токены принадлежат приложению, а не конкретному участнику команды.
Тестировщики приложения (вкладка «Команды») обходят проверку публичности на экране подтверждения установки для закрытых приложений. Пользователи из списка тестировщиков могут установить закрытое приложение; все остальные видят страницу «не найдено».

← Назад к документации