API и токены

Панель полностью управляется через HTTP API — интерфейс работает через тот же API. Полное описание методов со схемами запросов и ответов доступно на openapi.gameap.io.

Эта страница — о том, как в API аутентифицироваться.

Способы аутентификации

Токен передаётся заголовком:

Authorization: Bearer <токен>

Персональные токены доступа

Это основной способ для автоматизации: токен не привязан к сессии, не истекает и имеет собственный набор разрешений.

Создание

Создать токен можно в профиле или запросом:

curl -X POST https://panel.example.com:8025/api/tokens \
  -H "Authorization: Bearer <токен сессии>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-deploy", "abilities": ["server:list", "server:restart"]}'

Ответ содержит токен целиком:

{"token": "12|kJ3n8sQm..."}

Токен показывается только один раз. В базе хранится лишь его хеш SHA-256, восстановить значение невозможно — если потеряли, выпустите новый.

Формат токена — {идентификатор}|{секрет}. Разделитель | обязателен: передавайте значение целиком, как оно выдано.

Разрешения токена

Разрешения указываются при создании и ограничивают токен независимо от прав пользователя: токен не может больше, чем разрешено ему, и не может больше, чем разрешено его владельцу.

Разрешения с префиксом admin: может выдать только администратор — при попытке добавить их обычным пользователем запрос завершится ошибкой.

Актуальный список доступен запросом:

GET /api/tokens/abilities

Просмотр и отзыв

GET    /api/tokens        — список своих токенов
DELETE /api/tokens/{id}   — отозвать токен

В списке видны имя, разрешения и время последнего использования — по нему удобно находить неиспользуемые токены.

Смена пароля отзывает токены. Все персональные токены, созданные до смены пароля, перестают работать. После смены пароля выпустите токены заново.

Пример использования

TOKEN='12|kJ3n8sQm...'

# список серверов
curl -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com:8025/api/servers

# перезапуск сервера
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com:8025/api/servers/1/restart

Токен сессии

Выдаётся при входе по логину и паролю:

curl -X POST https://panel.example.com:8025/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login": "admin", "password": "..."}'

Формат токена — PASETO v4.local. Обычная сессия живёт 24 часа, с отметкой «запомнить меня» — 7 дней. Выход (POST /api/auth/logout) заносит токен в список отозванных, который проверяется при каждом запросе.

Если у пользователя включена двухфакторная аутентификация, вход возвращает не токен, а two_factor_required вместе с challenge_token; второй фактор подтверждается запросом POST /api/auth/2fa/verify. Подробности — Безопасность.

Для автоматизации сессионные токены неудобны: они истекают, а вход защищён ограничением частоты попыток и, возможно, капчей. Используйте персональные токены.

Короткоживущие токены

Нужны там, где токен вынужден передаваться в адресе страницы — подключение по WebSocket и скачивание файлов. Выдаются запросом POST /api/auth/short-lived-token, имеют префикс glst_, одноразовые и живут не дольше 10 секунд независимо от настроек.

Только такие токены принимаются в параметре запроса ?token=; персональный токен там передать нельзя — это защищает его от попадания в журналы веб-серверов и историю браузера.

Ограничения и коды ответов

Ограничение частоты действует только на вход и проверку второго фактора: 20 неудачных попыток с одного адреса и 5 на один логин за 15 минут. На запросы с персональным токеном ограничений по частоте нет.

CORS

Если API вызывается из браузера со стороннего адреса, перечислите допустимые источники в HTTP_ALLOWED_ORIGINS — полностью, со схемой. Подстановка * не поддерживается. См. Справочник config.env.