Авторизация в API: ключи и права

API-ключи

Ключ — это botgg_ и 43 случайных символа (256 бит). BotGG хранит только его SHA-256-хеш и короткий префикс вроде botgg_AbCd1234, чтобы вы узнали ключ в консоли, — показать полный ключ повторно не сможет никто, включая нас.

Откройте консоль, выберите сервер и перейдите в раздел API в боковом меню. Нужно право «Управлять сервером».
Создайте ключ: название (например, «Сайт»), нужные права и, при желании, срок действия — 30, 90 или 365 дней.
Сразу скопируйте ключ — он показывается только один раз — и сохраните его как секрет на своём сервере, например в BOTGG_API_KEY.

Ключ принадлежит одному серверу. Запрос к другому серверу вернёт 403 GUILD_MISMATCH.
Активных ключей на сервер: 2 на Free, 10 на Pro.
Просроченный ключ получает 401 API_KEY_EXPIRED, отозванный — сразу 401 API_KEY_REVOKED.
Создание и отзыв ключей записываются в журнал аудита консоли. Ключ продолжает работать, даже если его создатель ушёл: он принадлежит серверу, как токен бота.

Как передавать ключ

Передавайте ключ в заголовке Authorization каждого запроса по схеме Bearer. Никаких cookie и сессий — каждый запрос самостоятелен.

curl

curl -s https://console.botgg.app/api/v1/guilds/123456789012345678 \
  -H "Authorization: Bearer $BOTGG_API_KEY"

Без заголовка или при неверном формате вернётся 401 UNAUTHORIZED, с неизвестным ключом — 401 INVALID_API_KEY. Повторяющиеся ошибки с одного IP-адреса ограничиваются ответом 429 RATE_LIMITED.

Ответ · 401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="BotGG API"

{ "error": "API_KEY_REVOKED", "message": "This API key was revoked" }

Права (scopes)

Ключ может вызывать только эндпоинты, право на которые у него есть. Права независимы — bank:write не включает bank:read, — поэтому выдавайте каждому ключу ровно то, что нужно его коду. У каждого эндпоинта в справочнике указано его право.

Права API-ключей
Право	Что разрешает
`guild:read`	Чтение данных сервера — Название, иконка, число участников, язык и включённые функции сервера; роли, каналы и основные данные участника (роли, ник, дата входа).
`bank:read`	Чтение Банка — Балансы, история операций участника и таблица лидеров.
`bank:write`	Изменение балансов — Начислять и списывать валюту участникам. Каждое изменение попадает в журнал Банка.
`levels:read`	Чтение Уровней — Уровень, опыт и место участника, таблица лидеров по опыту.
`levels:write`	Изменение опыта — Начислять, списывать и задавать опыт участникам. Роли-награды и объявления о новом уровне работают как с командами /levels; каждое изменение попадает в журнал аудита.
`invites:read`	Чтение приглашений — Счётчики приглашений и место участника, таблица лидеров по приглашениям.
`invites:write`	Изменение бонусных приглашений — Добавлять и убирать бонусные приглашения, как /invites add. Награды за рубежи выдаются автоматически; каждое изменение попадает в журнал аудита.
`shop:read`	Чтение Магазина — Магазины, товары, инвентарь участников и история покупок.
`shop:write` Чувствительное	Управление Магазином — Покупать товары за участников (списывается с их баланса в Банке, роли выдаются), выдавать товары бесплатно, возвращать покупки, пополнять запас и включать или выключать товары.
`giveaways:read`	Чтение розыгрышей — Идущие и завершённые розыгрыши: число участников, победители и список участников.
`giveaways:write`	Управление розыгрышами — Запускать розыгрыши, завершать их досрочно и перевыбирать победителей. Бот публикует и обновляет их в Discord.
`flows:read`	Чтение сценариев — Список сценариев (название, вкл./выкл., триггер), статус и результат запусков.
`flows:run` Чувствительное	Запуск сценариев — Запускать включённые сценарии с триггером «Вручную» или «Вебхук» со своими входными данными. Сценарий выполняет все свои шаги; запуски учитываются в дневном лимите тарифа.
`tickets:read`	Чтение тикетов — Список и данные тикетов (автор, панель, статус, ответы формы) и сохранённые расшифровки закрытых тикетов.
`tickets:write`	Закрытие тикетов — Закрывать открытые тикеты с причиной — бот сохраняет расшифровку, пишет в лог и уведомляет автора, как при закрытии персоналом.
`applications:read`	Чтение заявок — Формы и поданные заявки, включая ответы кандидатов, голоса и решения.
`applications:write`	Решения по заявкам — Принимать и отклонять открытые заявки. Бот выдаёт / снимает роли формы, пишет кандидату в ЛС и обновляет обсуждение, как при решении персонала.
`appeals:read`	Чтение апелляций — Апелляции на бан с ответами, причиной бана и перепиской (внутренние заметки персонала не передаются).
`appeals:write` Чувствительное	Решения по апелляциям — Одобрять (разбанивать) или отклонять открытые апелляции с причиной; бот разбанивает и пишет в ЛС, как при решении персонала. Одобрение апелляции снимает бан с участника.
`moderation:read` Чувствительное	Чтение дел модерации — Дела модерации (предупреждения, тайм-ауты, кики, баны…) с причинами, ссылками-доказательствами и модераторами, и статус действий через API. Открывает доступ к истории модерации участников.
`moderation:write` Чувствительное	Модерация участников — Предупреждать, давать тайм-аут, кикать, банить и разбанивать от имени создателя ключа: только пока у него есть нужное право Discord, только участников ниже его и бота по роли, с причиной, не больше 10 действий в минуту. Любой, у кого есть этот ключ, может наказывать участников от вашего имени. Храните его в секрете и отзывайте, когда он не нужен.

Ответ · 403

HTTP/1.1 403 Forbidden

{ "error": "INSUFFICIENT_SCOPE", "message": "This API key lacks the \"bank:write\" scope", "required": "bank:write" }

Никаких запросов из браузера

Чтобы показать данные API на веб-странице, обращайтесь к API со своего бэкенда и передавайте результат на страницу.

Безопасность

Минимум прав. Если вы только показываете балансы или топ, создайте ключ лишь с правами на чтение.
Храните ключи как секреты — в переменной окружения или менеджере секретов, а не в коде и не в репозитории.
Ограничивайте срок и меняйте ключи. Задавайте срок действия; для ротации создайте новый ключ, разверните его и отзовите старый.
Утёкший ключ — отзывайте сразу. Ключи начинаются с botgg_, поэтому их легко найти поиском и сканерами секретов.
Только HTTPS. По обычному HTTP API недоступен.

Авторизация: API-ключи и права