Иногда удобнее не нажимать кнопки в браузере, а поручить управление программе: другому агенту, вашему скрипту или системе, которая следит за расходами. Для этого у «Прокси-агента» есть отдельная поверхность по адресу /api/agent/*. Через неё можно делать почти всё то же, что администратор в интерфейсе, — и при этом ничего не открывать в браузере.
Зачем это нужно
Обычно этим пользуются так: агенту передают только адрес вашего сервера и ключ управления, а он сам заводит модели, каналы связи и ключи доступа, а потом читает журналы и расходы. Человеку остаётся проверять результат, а не повторять одни и те же действия руками.
Это удобно и для разовых задач: например, перенести десяток ключей доступа на новый сервер или завести модели по списку из таблицы.
Ключ управления
Доступ закрыт ключом управления. Ключ передаётся в заголовке X-API-Key, а в переменной окружения PROXY_APP_HASH хранится не сам ключ, а его необратимая сумма (SHA-256, записанная строчными буквами). По файлу с переменными исходный ключ восстановить нельзя.
- Переменная не задана — поверхность отвечает «выключено» (503), и всё остальное на сервере работает как обычно.
- Ключ не совпал — ответ «не авторизован» (401).
- Неудачные попытки записываются в журнал вместе с адресом обратившегося. Сам ключ и его сумма в журнал не попадают никогда.
Ключ управления стоит держать в секрете: он открывает ровно то же, что и вход администратора, — всю настройку продукта.
Самопроверка
Отдельной книги по этой поверхности нет — её документация встроена в неё саму. Запрос GET /api/agent возвращает описание поверхности: как входить, какие понятия используются, что делается с секретами и полный перечень адресов с полями, ответами и возможными ошибками. Там же — пошаговый рецепт: завести ключ доступа, сделать через него запрос к модели, прочитать журнал.
Поэтому агенту достаточно знать адрес и ключ — остальное он прочитает сам. Список адресов и описание всегда совпадают с тем, что поверхность на самом деле умеет.
Что можно делать
- Модели и каналы связи — создавать, править, копировать, включать и выключать, проверять связь с поставщиком и посмотреть серверы по ссылке на подписку Happ до того, как канал сохранён. Всё то же, что в разделах Модели и цены и Каналы связи.
- Ключи доступа — создавать с пределами расхода, перевыпускать, менять пределы и списки разрешённых моделей и каналов, включать и удалять. Готовый ключ отдаётся ровно один раз.
- Журналы и аналитика — читать журнал запросов, журнал прокси-службы и все отчёты аналитики, включая состояние отправки данных в ClickHouse и досыл пропущенных дней.
- Скрытие секретов — вести правила, проверять их на примерах «вхолостую» и смотреть отчёты об утечках.
- Настройки — читать и записывать значения так же, как в окне «Настройки», — результат попадает в те же файлы конфигурации.
- Состояние — смотреть статус лицензии и сводку на «Главной».
Одноразовый код входа в браузер
Иногда программе нужно открыть интерфейс человеку. Пароль администратора для этого не нужен: запрос POST /api/agent/session выписывает одноразовый код на 5 минут. Человек вводит его при входе, код срабатывает один раз и выдаёт обычную сессию администратора на 90 дней.
Так агенту не нужно хранить ваш пароль — он лишь выписывает разовый пропуск. После первого использования или по истечении пяти минут код становится недействительным.
Что остаётся закрытым
Секреты прочитать нельзя ни в интерфейсе, ни по API. Ключи поставщиков, пароли каналов и приватные ключи VPN показываются теми же заглушками, что и в браузере: записать новый секрет можно, прочитать прежний — нет. Готовый ключ доступа показывается один раз при создании или перевыпуске, дальше видны только последние знаки.
Подробнее про то, где лежат секреты, — в разделе Доступ и безопасность.
Чего эта поверхность не делает
- Не заменяет пароль администратора. Выдать обычный вход в браузер она не может — только разовый код. Сам пароль по-прежнему задаётся переменными окружения.
- Не открывает секреты. Ключи и пароли остаются заглушками.
- Не заменяет лицензию. Настройку и управление можно вести и без ключа лицензии, но трафик через прокси без него не пойдёт. Сама поверхность лицензией не закрыта.
- Не смешивается с обычным доступом. Ключ управления не подойдёт для запросов к моделям, а ключ доступа — для управления.
Ответы и ошибки
Все запросы синхронные: ответ приходит сразу, долгих операций с ожиданием нет. Проверки связи — быстрые пробы, которые отвечают успехом или неуспехом.
Ошибки приходят единообразно: короткий признак и текст причины. Признаки типовые — ошибка в запросе, объект не найден, противоречие (такое имя уже занято или объект ещё используется). Тексты — на английском: это техническая поверхность для программ, а не раздел для человека.
Дальше: как устроена настройка в файлах — в разделе Настройки в файлах.