API-ключи
Доступ для плагинов, лаунчера и своих интеграций
По API-ключу авторизуется программа, а не человек. У каждого ключа свой набор прав и список адресов, с которых им можно пользоваться.
Создание
Утилиты → API-ключи → Создать. Три поля:
| Поле | Что это |
|---|---|
| Комментарий | Для кого выпущен ключ. Плагин hitech, Лаунчер |
| Разрешения | Список строк, синтаксис тот же, что у ролей |
| Доверенные IP-адреса | IP или маски вида 192.168.1.* |
Ключ показывается один раз, при создании. В базе он не лежит: там только хеш и первые шесть символов, по которым строку можно опознать в списке. Потеряли ключ — выпускайте новый.
Ключ без списка адресов не работает
Так задумано. Пустой список означает отказ во всех запросах. Утёкший ключ бесполезен, пока злоумышленник не окажется на разрешённом адресе.
Использование
GET /servers
Authorization: Api-Key <ваш-ключ>Именно Api-Key, а не Bearer. Запрос авторизуется, если ключ найден и IP запроса попадает под одну из масок.
Права для типовых задач
| Задача | Право |
|---|---|
| Плагин на сервере (UnicoreConnect) | kernel.unicore.connect |
| Лаунчер (UnicoreProvider) | kernel.unicore.provider |
| Своя интеграция | Точечный список того, что ей нужно |
Своей интеграции не выдавайте admin.*, соберите минимальный набор. Ключ с полными правами лежит в конфиге на игровом сервере и рано или поздно окажется не там.
Смена и отзыв
Права ключа меняются в его карточке. При сохранении все открытые вебсокет-соединения этого ключа принудительно рвутся. Клиент переподключится и получит уже новые права, а не продолжит жить со старыми.
Удаление ключа мгновенно закрывает доступ.
Свой клиент: минимальный пример
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.unicore.connect, kernel.unicore.provider или admin.dashboard выведены из-под него и там тоже: плагин опрашивает API часто, лимит для него смысла не имеет.
А вот ключ с узким набором прав под ограничение попадает. Учитывайте это, если ваша интеграция ходит в /auth.