Токены API
Токен API позволяет программе работать с API панели: вашему скрипту биллинга, боту, задаче мониторинга. Каждый токен действует от имени одного аккаунта администратора и никогда не выходит за пределы его доступа. Страница находится в Доступ → Токены API и открыта главным администраторам.
Как ограничивается токен
Токен сужается тремя способами, и каждый проверяется заново при каждом запросе:
- От имени: администратор, к которому он привязан. Токен видит то же, что этот администратор. Токен реселлера видит только пользователей этого реселлера и расходует его квоту. При удалении администратора удаляется и токен.
- Роль: уровень, на котором работает токен, не выше уровня его администратора. Понижение администратора понижает и токен.
- Области: маршруты, доступные токену внутри этой роли, в пересечении с правами роли его администратора. Сужение роли администратора сразу сужает все привязанные к нему токены, и перевыпускать ничего не нужно.
Изменение любого из них вступает в силу при следующем запросе токена.
Создание токена
- Добавить.
- Описание: для чего токен, чтобы потом его узнать.
- От имени: администратор, чей доступ получает токен.
- Роль: уровень, не выше уровня этого администратора.
- Области: оставьте Без ограничений для всех маршрутов, доступных роли (включая области, которые добавит следующий выпуск), или снимите отметку и выберите сами.
- Идентификатор аддона: для обычной интеграции оставьте пустым. Поле нужно для токена, который принадлежит дополнению, добавленному вручную (см. Страница дополнений).
- Запросов в минуту:
0означает значение панели по умолчанию, 120. - Срок действия (дней):
0— бессрочно. - Сохранить.
После этого панель показывает токен один раз. Скопируйте его, прежде чем закрыть окно: хранится только хеш, поэтому показать токен снова нельзя. Потерянный токен удаляют и заменяют новым.
TIP
Если в вашем аккаунте включена двухфакторная аутентификация, создание или удаление токена снова запрашивает код, если последний был введён больше десяти минут назад.
Передавайте токен с каждым запросом:
curl -H "Authorization: Bearer $NEXORA_TOKEN" \
https://panel.example.com/your-base-path/api/v1/me/api/v1/me отвечает, от имени какого администратора действует токен и какие области у него есть.
Области
Область :write включает соответствующую :read. Форма панели показывает названия из второго столбца; API и справочник API используют первый.
| Область | Как показана |
|---|---|
users:read | Видеть пользователей |
users:write | Создавать и изменять пользователей |
nodes:read | Видеть узлы |
nodes:write | Настраивать узлы |
tunnels:read | Видеть туннели |
tunnels:write | Настраивать туннели |
nodes:install | Устанавливать узлы по SSH |
templates:read | Видеть шаблоны |
templates:write | Изменять шаблоны |
pool:read | Видеть входящие, исходящие и наборы правил |
pool:write | Изменять входящие, исходящие и наборы правил |
certificates:read | Видеть сертификаты |
certificates:write | Выпускать и изменять сертификаты |
settings:read | Видеть настройки |
settings:write | Изменять настройки |
stats:read | Трафик, отчёты и состояние |
tools:write | Генераторы ключей |
admins:write | Управлять операторами и ролями |
tokens:write | Управлять токенами API |
license:write | Управлять лицензией |
backup:read | Скачивать резервные копии |
backup:write | Создавать и удалять резервные копии |
backup:deliver | Отправка файлов в чат бэкапов |
security:read | Видеть список блокировок |
security:write | Изменять список блокировок |
webhooks:read | Видеть подписчиков событий |
webhooks:write | Изменять подписчиков событий |
services:read | Видеть сервисы панели |
services:write | Настраивать и проверять сервисы панели |
Выдавайте программе минимум необходимого. Три области относятся к администрированию самой панели: admins:write, tokens:write и license:write. Не выдавайте их, если программе они действительно не нужны: токен без них не может создавать аккаунты и выпускать новые токены, поэтому утёкший токен не сможет закрепиться навсегда. backup:read выгружает всю базу со всеми учётными данными, а nodes:install входит на ваши серверы как root, поэтому обе требуют той же осторожности.
Несколько маршрутов закрыты для любого токена, какими бы ни были его области: смена собственного пароля, раскладка панели мониторинга, перезапуск панели, обновление панели и восстановление резервной копии. Несколько маршрутов открыты любому токену: /api/v1/me, список областей и каталог событий.
Ограничение частоты
У каждого токена есть бюджет запросов в минуту (120, если не задать другой). Каждый ответ содержит X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Запрос сверх бюджета получает 429 с Retry-After; подождите столько секунд перед следующим.
Список
| Столбец | |
|---|---|
| Описание | с меткой Дополнение: имя, если токен принадлежит дополнению |
| От имени | администратор, к которому он привязан |
| Роль | его уровень |
| Области | Без ограничений или число областей (наведите указатель, чтобы увидеть список) |
| Последнее использование | когда токен использовался последний раз; наведите указатель, чтобы увидеть адрес |
| Истекает | дата окончания срока или «никогда» |
После создания токен не редактируется: удалите его и создайте другой. Токен, принадлежащий дополнению, здесь удалить нельзя; он меняется или удаляется вместе с дополнением на странице Страница дополнений.
API
Справочник API вверху страницы открывает справочник для этой установки с уже подставленными её адресами: каждый маршрут, нужная ему область, списки и постраничный вывод, повторы с Idempotency-Key и коды ответов. Тот же материал есть в Справочник API.
Стройте интеграции на префиксе /api/v1. Это стабильный публичный контракт. Префикс /api без версии принадлежит интерфейсу панели и может меняться вместе с ним.
См. также
- Администраторы и Роли: что может администратор токена.
- Вебхуки и события: получать события вместо постоянных опросов.
- Справочник API: справочник API.
- Журнал аудита: что изменил токен.