Ключи управления

Ключ управления (sk-aitunnel-mgmt-…) управляет аккаунтом через API: API-ключи, пресеты, платежи, расход всего аккаунта. Модели он не вызывает.

Адрес

https://api.aitunnel.ru/v1/aitunnel/…

Авторизация

Authorization: Bearer sk-aitunnel-mgmt-xxx

Где создать

В кабинете: API-ключи → Ключи управления

Чем отличается от API-ключа

API-ключ тратит деньги: с ним идут запросы к моделям. Ключ управления настраивает аккаунт: его отдают скрипту развёртывания, биллингу или панели администратора, которым незачем вызывать модели.

	API-ключ	Ключ управления
Префикс	`sk-aitunnel-`	`sk-aitunnel-mgmt-`
Вызывает модели	Да	Нет, ответ `403`
Что видит	Свои запросы и расход, баланс аккаунта	Весь аккаунт, в пределах своих прав
Меняет аккаунт	Нет	Да, в пределах своих прав
Чем ограничен	Бюджет, модели, IP, срок	Права, IP, срок
Секрет	Владелец может посмотреть снова в кабинете	Показывается один раз
Сколько можно	Зависит от баланса	20 действующих на аккаунт

Создание

Ключ управления создаётся только в кабинете: страница «API-ключи», вкладка «Ключи управления», кнопка «Новый ключ». Через API его нельзя ни создать, ни посмотреть, ни отозвать — ни API-ключом, ни другим ключом управления.

Имя — до 64 символов. Оно же стоит в журнале активности рядом с каждым изменением.
Права — хотя бы одно. Изменить их потом нельзя: создайте новый ключ.
IP-адреса и срок — необязательно, см. ниже.
Перед созданием кабинет просит подтвердить личность паролем, кодом или passkey, если с последнего подтверждения прошло больше 10 минут.
На аккаунт — до 20 действующих ключей. Отозванные не считаются.

В списке ключ виден по подсказке — префиксу и последним четырём символам (sk-aitunnel-mgmt-…x7Qp). Там же его права, срок, время и IP последнего запроса. Отозванный ключ перестаёт работать со следующего запроса.

Как вызвать

Ключ передаётся так же, как API-ключ: Authorization: Bearer sk-aitunnel-mgmt-xxx или заголовок x-api-key. Адреса те же, включая зеркало ru-api.aitunnel.ru. Пример — баланс аккаунта, ему нужно право billing:read.

curl https://api.aitunnel.ru/v1/aitunnel/balance \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

JSON

{
  "balance": 1250.5
}

Права

Каждый метод называет право, которое ему нужно. x:write включает x:read. Других связей нет: keys:write не открывает расход, billing:write не открывает ключи.

Право	Смысл
`usage:read`	Расход и запросы всего аккаунта: `GET /usage`, `GET /requests` с фильтрами, выгрузкой CSV и сохранёнными логами, задачи
`keys:read`	Список API-ключей и их настройки
`keys:write`	Создать, изменить, поставить на паузу, сбросить секрет, дублировать и удалить API-ключ
`presets:read`	Список пресетов
`presets:write`	Создать, изменить и удалить пресет
`billing:read`	Баланс, платежи, сохранённые карты и автопополнение, история баланса и рефералы, организации и счета, закрывающие документы
`billing:write`	Начать пополнение, выставить счёт, списать с сохранённой карты, привязать и удалить карту, настроить автопополнение, сохранить организацию, подключить ЭДО
`profile:read`	`GET /me`, профиль и настройки хранения логов
`profile:write`	Изменить имя, тему, уведомления о балансе и настройки хранения логов

Давайте ключу только то, что нужно его задаче: дашборду расходов хватит usage:read, скрипту, который выдаёт ключи клиентам, — keys:write.

IP-адреса и срок

IP-адреса. До 50 адресов или подсетей CIDR, IPv4 и IPv6: 203.0.113.7, 203.0.113.0/24, 2001:db8::/32. Запрос с другого адреса получает 403. Без списка ключ работает с любого адреса.
Через зеркало ru-api.aitunnel.ru сравнивается ваш адрес, а не адрес зеркала.
Срок. Дата и время в будущем. После этого момента ключ отвечает 401. Продлить срок нельзя: создайте новый ключ.
Если владелец запланировал удаление аккаунта, ключи управления отвечают 403.

Журнал активности

Всё, что ключ управления изменил, записывается в журнал активности аккаунта: Настройки → Безопасность. Пропустить запись нельзя: изменение, у которого нет собственного вида записи, попадает в журнал как запрос ключа, с методом и путём.

В записи: что сделано, имя ключа управления, IP, страна и город, устройство.
Записываются изменения. Чтение (GET) в журнал не попадает.
Создание и отзыв самого ключа управления тоже в журнале.
Журнал хранится 30 дней и читается только в кабинете.

Чего ключ не может

Вызывать модели: /v1/chat/completions, /v1/embeddings, /v1/models и остальные методы из справочника API отвечают 403.
Вызвать GET /aitunnel/key: он описывает API-ключ, которым сделан запрос.
Создавать, читать и отзывать ключи управления.
Прочитать секрет существующего API-ключа. Секрет приходит только в ответе на создание, дублирование и сброс.
Менять то, что защищает аккаунт: пароль, почту, двухфакторную аутентификацию, passkey, сессии. Удалить аккаунт или все сохранённые логи.

Настройки безопасности, Студия, промокоды, задания и ссылки для бухгалтера есть только в кабинете: ни одно право их не открывает.

Ошибки

Неверный ключ — 401 с типом authentication_failed. Ключ верный, но действие ему не разрешено — 403 с типом permission_denied. Сообщение говорит, чего не хватило.

Статус	Сообщение	Когда
`401`	«Недействительный токен. Токен должен быть создан в нашем сервисе aitunnel.ru»	Ключа с таким секретом нет
`401`	«Этот ключ управления отозван. Создайте новый на странице https://aitunnel.ru/panel/keys»	Ключ отозван в кабинете
`401`	«Срок действия этого ключа управления истёк. Создайте новый на странице https://aitunnel.ru/panel/keys»	Прошёл срок, заданный при создании
`403`	«У этого ключа управления нет права «keys:write».»	Метод требует права, которого у ключа нет
`403`	«Этот метод не работает с ключом управления. Используйте обычный API-ключ.»	Методы моделей и `GET /aitunnel/key`
`403`	«Этот метод недоступен для ключей управления: он работает только в кабинете.»	Метод принимает только вход в кабинет
`403`	«IP-адрес «203.0.113.9» не разрешён для этого API-ключа.»	Запрос пришёл с адреса не из списка ключа. Текст общий для обоих видов ключей
`403`	«Аккаунт запланирован к удалению, API-ключи отключены. Отменить удаление можно в настройках: https://aitunnel.ru/panel/settings»	Владелец запланировал удаление аккаунта
`403`	«Этот метод не работает с API-ключом. Нужен ключ управления с правом «keys:read»: https://aitunnel.ru/panel/keys»	Метод управления вызван API-ключом
`429`	«Слишком много неудачных попыток авторизации. Повторите попытку через минуту.»	С одного IP подряд идут запросы с неверным ключом

403

{
  "error": {
    "code": 403,
    "type": "permission_denied",
    "message": "У этого ключа управления нет права «keys:write».",
    "request_id": "req-0J9fQk2vXc8LrT1mNbZa4e"
  }
}

Ошибку в теле запроса методы управления возвращают как 400 с типом invalid_request: в error.metadata.fields — список { field, message } по каждому неверному полю. Общий формат ошибок — в ошибках и отладке.

Методы

API-ключи — /keys: список, создание, бюджет, пауза, сброс секрета.
Пресеты — /presets.
Платежи — /payments: пополнение, карты, автопополнение.
Счета и организации — /payments/companies, /payments/invoices.
История баланса — /balance/history, /referrals.
Закрывающие документы — /documents.
Профиль — /profile, /request-logs/settings.
Задачи — /jobs.
Расход и запросы — /usage, /requests по всему аккаунту.