API-токены и OpenAPI

Все интерфейсы, которые использует панель управления Gately, доступны по HTTP. Скрипты и автоматизация авторизуются с помощью API-токена, а описание интерфейсов генерируется программой автоматически по зарегистрированным маршрутам.

API-токены

Путь в интерфейсе: боковая панель, группа «Система» → «API-токены».

Создание токена

Нажмите «Создать токен» и заполните поля:

Параметр	Описание
Название	Обязательно, до 64 символов, обозначает назначение, например «Скрипт мониторинга»
Срок действия	«Бессрочно», 7 дней, 30 дней, 90 дней, 1 год или произвольная дата; произвольное время должно быть позже текущего
Права	Обязательно, выберите хотя бы одно. По умолчанию при создании права не выдаются

Один экземпляр хранит не более 100 токенов.

После создания токен в открытом виде показывается в окне только один раз в формате gtl_ и 48 шестнадцатеричных символов. На диске хранится только хеш SHA-256, поэтому утерянный токен можно только «Сгенерировать заново», при этом старое значение сразу становится недействительным. В списке токены опознаются по подсказке вида gtl_xxxx…yyyy, также показываются время последнего использования и IP-адрес источника (запись на диск отстаёт не более чем на минуту).

В токене можно изменить название, права, срок действия и переключатель включения; изменения применяются сразу, а значение токена остаётся прежним. У просроченного токена можно оставить прежний срок и менять только другие поля.

Способ авторизации

Передавайте заголовок Authorization: Bearer <токен>:

bash

curl -H "Authorization: Bearer gtl_xxxx" http://localhost:16680/api/status

В теле запроса используется Content-Type: application/json, ошибки всегда возвращаются в виде {"error": "описание"}. Если токен отключён, просрочен или не существует, запрос проверяется как сессия входа и в итоге возвращает ошибку «не выполнен вход».

Области прав

Права записываются как <область>:read или <область>:write, право записи включает право чтения. Область — это ID функционального модуля (например, ddns, portforward, notify, backup) плюс три встроенные области:

Область	Название	Доступные права	Интерфейсы
`status`	Состояние системы	`status:read`	`/api/status`, `/api/system/info`, `/api/system/update`
`logs`	Системные журналы	`logs:read`	`/api/logs`
`import`	Импорт конфигурации Lucky	`import:write`	`/api/import/lucky`

Шаблоны:

Запись	Значение
`*:read`	Чтение всех модулей
`:write` или ``	Чтение и запись всех модулей
`ddns:read`	Только чтение DDNS

Необходимые для интерфейса права определяются путём и методом:

Путь /api/<модуль>/... требует прав области <модуль>: для GET и HEAD нужно read, для остальных методов write.
Журнал модуля GET /api/<модуль>/logs относится к чтению, а очистка журнала (DELETE) — к записи.
Следующие GET-интерфейсы возвращают чувствительные данные или открывают интерактивный канал, поэтому требуют write: пути, содержащие сегменты ws (WebSocket-терминал), exec, download, export, read, config, preview-archive, например скачивание сертификатов, выполнение команд в контейнере и чтение файлов.
GET /api/session и GET /api/openapi.json принимают любой действующий токен.

Операции, запрещённые для токенов

Следующие интерфейсы принимают только сессию входа, а токен всегда получает 403:

Аккаунт и двухфакторная аутентификация: /api/account
Управление токенами: /api/tokens
Системные настройки, системный токен, перезапуск, онлайн-обновление: /api/system/settings, /api/system/token, /api/system/restart, /api/system/upgrade
Скачивание и восстановление резервной копии конфигурации: /api/system/backup, /api/system/restore
Скачивание локальных файлов резервных копий: /api/backup/local
Настройки безопасности веб-терминала: /api/webterminal/security
Вход и выход: /api/login, /api/logout

Запрос с недостаточными правами возвращает Токену не хватает права <право>, а в системный журнал записывается предупреждение с названием токена, IP-адресом источника и отклонённым интерфейсом.

Устаревший токен

Единый глобальный токен старых версий при обновлении автоматически переносится в токен «Устаревший токен (перенесён из старой версии)» с правами *, в списке он помечен как «устаревший». Рекомендуется создать новые токены с нужными правами и удалить его; «Сгенерировать заново» для устаревшего токена также снимает эту метку.

Рекомендация

Создавайте отдельный токен для каждого скрипта, отмечайте только нужные ему права и задавайте срок действия. При утечке достаточно удалить или перегенерировать один соответствующий токен.

OpenAPI и документация интерфейсов

Страница документации в интерфейсе

Боковая панель, группа «Система» → «Документация API». На странице показаны Base URL и описание аутентификации, все интерфейсы сгруппированы по функциям, доступен поиск по пути или описанию. Раскрыв интерфейс, можно увидеть необходимые права, параметры, поля тела запроса и пример curl, который можно скопировать. Интерфейсы, требующие сессии входа, помечены «Только сессия входа» и примера curl не имеют.

Получение документа OpenAPI

Когда экземпляр запущен, GET /api/openapi.json возвращает документ OpenAPI 3.0, который может прочитать любой действующий токен или сессия входа:

bash

curl -H "Authorization: Bearer gtl_xxxx" http://localhost:16680/api/openapi.json -o openapi.json

Документ использует схему безопасности bearerAuth и добавляет для каждого интерфейса расширенные поля:

Расширенное поле	Значение
`x-required-scope`	Права токена, необходимые для доступа к интерфейсу
`x-token-allowed`	Разрешён ли доступ токену, `false` означает только сессию входа
`x-scope-domains` (корень документа)	Список всех областей прав

Список интерфейсов для командной строки и MCP считывается из этого документа.

Экспорт из командной строки

Параметр -api-docs собирает приложение во временном каталоге конфигурации (порт не слушается, существующая конфигурация не затрагивается), записывает документы в указанный каталог и завершается:

bash

gately -api-docs ./api-docs

Создаются два файла:

openapi.json: описание OpenAPI 3.0
API.md: документация интерфейсов в Markdown с быстрым стартом, таблицей областей прав и таблицами интерфейсов по группам

Примеры вызовов

bash

# Посмотреть состояние системы (нужно status:read)
curl -H "Authorization: Bearer gtl_xxxx" http://localhost:16680/api/status

# Список всех заданий DDNS (нужно ddns:read)
curl -H "Authorization: Bearer gtl_xxxx" http://localhost:16680/api/ddns/tasks

# Немедленно синхронизировать задание DDNS (нужно ddns:write, key берётся из списка на предыдущем шаге)
curl -X POST -H "Authorization: Bearer gtl_xxxx" http://localhost:16680/api/ddns/tasks/KEY/sync

# Получить только записи журнала модуля с номером больше 10 (нужно ddns:read)
curl -H "Authorization: Bearer gtl_xxxx" "http://localhost:16680/api/ddns/logs?since=10"

# Получить только 200 последних записей; передайте наименьший номер в before, чтобы листать назад
curl -H "Authorization: Bearer gtl_xxxx" "http://localhost:16680/api/ddns/logs?limit=200"
curl -H "Authorization: Bearer gtl_xxxx" "http://localhost:16680/api/ddns/logs?before=1200&limit=200"

Полный список интерфейсов

Все интерфейсы, параметры и необходимые права приведены в списке интерфейсов API.

API-токены и OpenAPI ​