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

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

Адрес
https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/…
Авторизация
Authorization: Bearer sk-aitunnel-mgmt-xxx
Где создать
В кабинете: API-ключи → Ключи управления

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

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

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

Создание

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

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

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

Как вызвать

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

curl https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/balance \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"
JSON
{
  "balance": 1250.5
}

Права

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

ПравоСмысл
usage:readРасход и запросы всего аккаунта: GET /usage, GET /requests с фильтрами, выгрузкой CSV и сохранёнными логами, задачи
keys:readСписок API-ключей и их настройки
keys:writeСоздать, изменить, поставить на паузу, сбросить секрет, дублировать и удалить API-ключ
presets:readСписок пресетов
presets:writeСоздать, изменить и удалить пресет
knowledge:readСписок баз знаний, их файлов и статусов индексации
knowledge:writeСоздать, изменить и удалить базу знаний, загрузить и удалить файл, повторить индексацию
billing:readБаланс, платежи, сохранённые карты и автопополнение, история баланса и рефералы, организации и счета, закрывающие документы
billing:writeНачать пополнение (ссылка на страницу оплаты), выставить счёт, сохранить организацию, подключить ЭДО, выключить автопополнение. С карты не списывает
billing:chargeВсё, что billing:write, и деньги без участия владельца: списать с сохранённой карты, привязать и удалить карту, включить или изменить автопополнение. Приложениям через вход через AITunnel не выдаётся
profile:readGET /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.83.141.93.205.nip.io сравнивается ваш адрес, а не адрес зеркала.
  • Срок. Дата и время в будущем. После этого момента ключ отвечает 401. Продлить срок нельзя: создайте новый ключ.
  • Если владелец запланировал удаление аккаунта, ключи управления отвечают 403.

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

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

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

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

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

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

Ошибки

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

СтатусСообщениеКогда
401«Недействительный токен. Токен должен быть создан в нашем сервисе aitunnel.83.141.93.205.nip.io»Ключа с таким секретом нет
401«Этот ключ управления отозван. Создайте новый на странице https://aitunnel.83.141.93.205.nip.io/panel/keys»Ключ отозван в кабинете
401«Срок действия этого ключа управления истёк. Создайте новый на странице https://aitunnel.83.141.93.205.nip.io/panel/keys»Прошёл срок, заданный при создании
403«Этот ключ управления приостановлен, потому что с ним не было запросов 90 дней. Возобновить его можно на странице https://aitunnel.83.141.93.205.nip.io/panel/keys/management»Ключ, выданный приложению через вход через AITunnel, 90 дней не использовался. Владелец возобновляет его в кабинете
403«У этого ключа управления нет права «keys:write».»Метод требует права, которого у ключа нет
403«Этот метод не работает с ключом управления. Используйте обычный API-ключ.»Методы моделей и GET /aitunnel/key
403«Этот метод недоступен для ключей управления: он работает только в кабинете.»Метод принимает только вход в кабинет
403«IP-адрес «203.0.113.9» не разрешён для этого API-ключа.»Запрос пришёл с адреса не из списка ключа. Текст общий для обоих видов ключей
403«Аккаунт запланирован к удалению, API-ключи отключены. Отменить удаление можно в настройках: https://aitunnel.83.141.93.205.nip.io/panel/settings»Владелец запланировал удаление аккаунта
403«Этот метод не работает с API-ключом. Нужен ключ управления с правом «keys:read»: https://aitunnel.83.141.93.205.nip.io/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 } по каждому неверному полю. Общий формат ошибок — в ошибках и отладке.

Методы