Ключи API администратора

В панели администратора: System › Settings › API & AI agents (/agent/keys), вкладка API keys. На этой же странице доступны вкладки Connect an AI, Connected apps и Activity.

Назначение

Ключ API администратора (префикс ak_) позволяет AI-клиенту или скрипту управлять вашей панелью строго в рамках выданных прав. Он работает в API администратора по адресу /v1/admin/ и на эндпоинте MCP администратора /mcp/admin. В других местах он не действует.

Отличие от ключей клиентов

Клиенты создают ключи, начинающиеся с vk_, в панели клиента (Ключи API и области доступа). Они имеют доступ только к API клиента и /mcp. Ключ ak_ отклоняется в API клиента, а ключ vk_ — в API администратора.

Требования

Параметр	Требование
Роль	Вы должны войти в панель администратора. Ключи не могут создавать другие ключи.
Демо	В демо-панели страница доступна только для чтения: ключи нельзя создавать или отзывать.
Сетевая доступность	Клиент должен иметь доступ к https://cloud.example.com/mcp/admin или /v1/admin/... на вашей панели (проверьте межсетевой экран, если настроены ограничения по IP).

Создание ключа

1. Перейдите в System › Settings › API & AI agents и оставайтесь на вкладке API keys.

2. Нажмите Create new key.

3. Заполните форму:

   Поле	Правила
   Name	До 60 символов, например «Claude Code on my laptop».
   Скоупы	Отметьте хотя бы одну. См. Scopes. Начните только с admin:read.
   Срок действия	1, 7, 30, 60 или 90 дней. По умолчанию 30. Максимум 90. Создать ключ без срока действия нельзя.
   Диапазоны IP (необязательно)	По одному адресу IPv4, IPv6 или CIDR на строку, например 203.0.113.0/24 или 2001:db8::/48. Не более 32. Оставьте пустым, чтобы разрешить любые IP.
   Запросов в минуту	От 1 до 6000. По умолчанию 120.

4. Нажмите Create key. В появившемся окне ключ будет показан один раз, например ak_XXXX. Скопируйте его сейчас: NexCMP сохраняет только хеш и больше никогда его не покажет.

5. Нажмите I have saved the key. Откройте вкладку Connect an AI, чтобы получить готовые команды, уже содержащие только что созданный ключ (доступно только на этой странице до ее обновления).

Скоупы

Ключ может использовать только те инструменты и эндпоинты, которые разрешены его областями доступа. Права на запись не включают доступ на чтение: ключу, которому требуется чтение и запись, также необходим admin:read.

Скоуп	Что разрешает
admin:read	Чтение настроек, каталога, клиентов, биллинга и логов. Секретные данные никогда не возвращаются.
catalog:write	Тарифы, шаблоны ОС, квоты, промокоды.
infra:write	Источники инфраструктуры (CloudStack, Proxmox), зоны, серверы.
billing:write	Платежные шлюзы, валюта, счета, балансы. Финансовые операции требуют подтверждения.
customers:write	Клиенты и реселлеры.
settings:write	Общие настройки, брендинг, email, правовые страницы, модули, уведомления.
ai:write	Провайдер AI и функции AI.
secrets:write	Запись паролей и ключей API. Их можно задать, но нельзя прочитать обратно.

Для установки секрета требуются две области доступа

Любой запрос, передающий пароль, ключ API или токен (пароль SMTP, платежный ключ, токен бота Telegram, ключ провайдера AI, учетные данные CloudStack или Proxmox), требует secrets:write и область доступа соответствующего раздела (например, settings:write для SMTP). Если вы предпочитаете вводить секреты вручную, оставьте secrets:write отключенным и укажите их в панели администратора.

Отозвать ключ

1. Найдите ключ в таблице (статус Active, Expired или Revoked; в столбце Last used указаны время и клиент).
2. Нажмите Revoke и подтвердите действие.

Ключ перестает действовать мгновенно. Отзыв необратим; если ключ понадобится снова, создайте новый.

Что никогда не может делать ключ

Ключ ни при каких условиях не дает доступа к этим разделам, независимо от его областей доступа. Для них требуется войти в панель администратора.

• Создание или изменение пользователей-администраторов, 2FA и безопасности входа, сессий администраторов и токенов API администратора.
• Создание, просмотр списка или отзыв ключей администратора, подключений OAuth и аккаунтов AI, а также использование AI Console.
• Резервное копирование или восстановление панели, ее обновление или изменение лицензии.
• Вход от имени клиента или реселлера, открытие консоли клиента, чтение учетных данных виртуальных машин или kubeconfig, установка SSH Keys, а также отправка или сброс паролей.
• Изменение модулей сети и маршрутизации (BGP, FRR, RTBH, XDP, интерфейсы, статические маршруты и маршрутизация на основе политик, NAT), внешних агентов и интеграции портала. Они доступны только для чтения.
• Изменение таких параметров, как demo_*, admin_*, списки хостов, passkey, секреты повторной аутентификации и капчи.

Все, что не охвачено правилами, по умолчанию закрыто для записи и доступно для чтения с admin:read.

Действия, требующие вашего подтверждения

Они выполняются только после того, как вы одобрите предварительный просмотр (см. Двухэтапное подтверждение):

• Изменение баланса клиента или кошелька реселлера, выплата средств, биллинговые записи, курс обмена валют.
• Изменение цен (тарифных планов, массовое создание планов, тарификация образов и хранилища) и создание скидочных или денежных кодов.
• Сохранение учетных данных платежного шлюза или подключения к CloudStack.
• Удаление любых объектов, блокировка или удаление клиента, изменение лимитов клиента, приостановка или закрытие реселлера.
• Операции с серверами клиентов или создание платного сервера для клиента.
• Изменение глобальных переключателей, настроек безопасности входа или параметров оплаты через общие настройки.

Двухэтапное подтверждение

Когда запрос требует подтверждения, изменения сразу не применяются. Возвращается ответ HTTP 428 с confirm_required, confirm_token, preview (метод, путь, причина, новые значения и, если доступны, текущие значения) и expires_in: 300.

1. Клиент отображает предварительный просмотр.
2. После вашего одобрения он повторяет тот же самый запрос (с теми же методом, путем и телом) с заголовком X-Confirm-Token: <confirm_token>. Инструменты MCP вместо этого принимают аргумент confirm_token.
3. Токен действует один раз и истекает через 5 минут.

Ключи, созданные в панели администратора для AI Chat, можно подтвердить только на экране: в ответе возвращается confirm_in: "ui", и в панели администратора появляется карточка подтверждения. AI не может одобрить его.

Ограничение частоты запросов и правила IP

• При превышении поминутного лимита запрос возвращает rate_limited (HTTP 429) с Retry-After: 60.
• Если заданы диапазоны IP, запросы с любых других адресов возвращают ip_not_allowed (HTTP 403).

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

На вкладке Activity перечислены все запросы, выполненные с ключом, начиная с последних: время, ключ, клиент, способ поступления (http, mcp, chat, cli, confirm, preview), метод и путь, инструмент, HTTP-статус, IP-адрес и (скрытые) подробности. Можно выполнять поиск по пути, инструменту или имени ключа, отображать только ошибки (HTTP 400 и выше) или только запросы, ожидающие подтверждения (428 и выше), а также ограничить период последним часом, 24 часами или 7 днями. NexCMP хранит последние 200,000 записей. Изменения, внесенные через ключ, также отображаются в Logs › Admin actions под именем ak:<admin>/<key name>.

Проверка

Проверьте ключ только для чтения с любого компьютера, входящего в диапазон IP:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

Вы получите JSON-список инструментов, разрешенных вашими областями действия. Выполните один из них:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

Время Last used ключа обновится, а вызов появится во вкладке Activity. Полный список инструментов и спецификация OpenAPI (/v1/admin/openapi.json) описаны в разделе Подключение AI-клиента.

Ошибки

Ошибки возвращаются в формате JSON: {"error": {"code": "...", "message": "..."}}.

HTTP	code	Значение	Решение
401	invalid_key	Ключ отсутствует, имеет неверный формат или неизвестен. Также возвращается при использовании ключа ak_ для пути, не относящегося к административным.	Проверьте ключ; используйте его только для /v1/admin/ и /mcp/admin.
401	key_expired	Срок действия ключа истек.	Создайте новый ключ.
401	key_revoked	Ключ был отозван.	Создайте новый ключ.
403	ip_not_allowed	IP-адрес отправителя запроса находится за пределами диапазонов IP ключа.	Выполните запрос с разрешенного IP-адреса или создайте ключ с нужным диапазоном.
403	local_only_key	Ключ, созданный для AI Chat или серверного CLI, был использован с другого компьютера.	Такие ключи работают только на самом сервере панели.
403	insufficient_scope	У ключа нет необходимой области действия; ответ содержит required_scope.	Создайте ключ с этой областью действия.
403	forbidden_for_keys	Эндпоинт или параметр, который вы пытаетесь изменить, закрыт для ключей.	Выполните это в панели администратора.
403	demo_read_only	Панель находится в демо-режиме, а запрос выполняет запись.	Используйте панель не в демо-режиме.
403	confirm_in_ui	Это действие необходимо подтвердить на экране в панели администратора.	Одобрите карточку подтверждения.
428	confirm_required	Предпросмотр готов; ничего не изменилось. Содержит confirm_token.	Отобразите предпросмотр, затем повторите запрос с X-Confirm-Token.
409	confirm_expired	Срок действия токена превышает 5 минут.	Отправьте запрос повторно для получения нового предпросмотра.
409	confirm_mismatch	Токен относится к другому запросу (отличается метод, путь или тело).	Повторите полностью идентичный запрос.
409	confirm_invalid	Неизвестный или уже использованный токен.	Отправьте запрос повторно для получения нового предпросмотра.
429	rate_limited	Слишком много запросов за эту минуту.	Подождите Retry-After.
400	invalid_path	Путь содержит запрещенные последовательности символов.	Используйте обычный путь.
413	too_large	Размер тела запроса превышает 10 MB.	Отправьте меньше данных.
400	invalid_argument	Аргумент инструмента отсутствует, неизвестен или имеет неверный тип; в сообщении указано его имя.	Исправьте аргумент.

Ограничения и примечания

• Используйте ключи с коротким сроком действия и ограниченными правами. Предпочтительно создавать отдельный ключ для каждого клиента, чтобы можно было отозвать конкретный ключ.
• Возможности ключа определяются его областями действия. Комбинация secrets:write и billing:write наиболее чувствительна; финансовые операции все равно останавливаются на этапе предпросмотра.
• Ключи, созданные автоматически (для AI Chat, серверного CLI), действуют всего несколько минут и работают только на сервере панели.
• Чтобы мгновенно отключить AI-клиент, отзовите его ключ. OAuth-подключения отзываются на вкладке Connected apps (OAuth connectors).