API-ключи

Доступ для плагинов, лаунчера и своих интеграций

По API-ключу авторизуется программа, а не человек. У каждого ключа свой набор прав и список адресов, с которых им можно пользоваться.

Создание

Утилиты → API-ключи → Создать. Четыре поля:

Поле	Что это
Комментарий	Для кого выпущен ключ. `Плагин hitech`, `Лаунчер`
Разрешения	Список строк, синтаксис тот же, что у ролей
Серверы	С какими серверами работает ключ. Пусто — со всеми
Доверенные IP-адреса	IP или маски вида `192.168.1.*`

Ключ показывается один раз, при создании. В базе он не лежит: там только хеш и первые шесть символов, по которым строку можно опознать в списке. Потеряли ключ — выпускайте новый.

Ключ без списка адресов не работает

Так задумано. Пустой список означает отказ во всех запросах. Утёкший ключ бесполезен, пока злоумышленник не окажется на разрешённом адресе.

Использование

GET /servers
Authorization: Api-Key <ваш-ключ>

Именно Api-Key, а не Bearer. Запрос авторизуется, если ключ найден и IP запроса попадает под одну из масок.

Ключу можно указать, с какими серверами он работает. Тогда запрос, где фигурирует другой сервер, получает 403 с текстом «Ключ выдан для другого сервера» — в пути, в теле или в параметрах запроса, включая списки серверов.

GET /cabinet/money/user/skytech/8f14e45f-...
Authorization: Api-Key <ключ, выданный для hitech>

403 Forbidden

Ограничение действует и на вебсокеты: события доната (give_group, take_group, give_permission, take_permission) приходят такому ключу только по его серверам. Ключ без списка серверов, как и раньше, получает всё.

Один сервер — один ключ

Ключ лежит в конфиге на игровом сервере, а конфиги утекают вместе с бэкапами и скриншотами. Ключ, выданный на один сервер, после утечки не даст трогать соседние.

Права для типовых задач

Задача	Право
Плагин на сервере (UnicoreConnect)	`kernel.connect`
Лаунчер (UnicoreProvider)	`kernel.provider`
Лаунчсервер Laminara (UnicoreProviderLaminara)	`kernel.laminara.provider`
Своя интеграция	Точечный список того, что ей нужно

Своей интеграции не выдавайте panel.*, соберите минимальный набор. Ключ с полными правами лежит в конфиге на игровом сервере и рано или поздно окажется не там.

Смена и отзыв

Права ключа меняются в его карточке. При сохранении все открытые вебсокет-соединения этого ключа принудительно рвутся. Клиент переподключится и получит уже новые права, а не продолжит жить со старыми.

Удаление ключа мгновенно закрывает доступ.

Свой клиент: минимальный пример

curl -s https://api.example.com/servers \
  -H 'Authorization: Api-Key ваш-ключ' \
  -H 'x-locale: ru'

import requests

API = "https://api.example.com"
HEADERS = {"Authorization": "Api-Key ваш-ключ"}

servers = requests.get(f"{API}/servers", headers=HEADERS).json()
for server in servers:
    print(server["id"], server["name"])

Проверяйте IP, а не только ключ

Чаще всего при подключении ловят 401 с совершенно правильным ключом. Почти всегда виноват адрес: сервер видит не тот IP, который вы ожидаете. Посмотрите в логах, с какого адреса пришёл запрос, и добавьте именно его. За прокси не забудьте про TRUST_PROXY.

Ограничения по частоте

Троттлинг стоит на ветке /auth/* и на активации подарочных кодов, остальное API не ограничено. Ключи с правами kernel.connect, kernel.provider или panel.access выведены из-под него и там тоже: плагин опрашивает API часто, лимит для него смысла не имеет.

А вот ключ с узким набором прав под ограничение попадает. Учитывайте это, если ваша интеграция ходит в /auth.