Ключи API и области доступа

В портале: API keys (/api-keys). В панели администратора: Customers › Customers › API keys (/customers/apikeys).

Назначение

API key позволяет скрипту, задаче CI, cmp CLI или ИИ-ассистенту (MCP) вызывать REST API от имени конкретного клиента с предоставленными правами (scopes). Клиентские ключи начинаются с vk_. Они могут читать и управлять сервисами, но никогда не имеют доступа к деньгам или самой учетной записи.

Требования

Параметр	Требование
Клиент	Авторизованная сессия в портале (ключ не может создавать или изменять другие ключи, как и администратор, вошедший от имени клиента).
Переключатель	Ключи API включены по умолчанию. Если они отключены, запросы возвращают 401 api_keys_disabled.
Зависимости	Scopes продукта отображаются только тогда, когда этот продукт включен на сайте.

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

1. Войдите в портал и откройте API keys.

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

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

   Поле	Правило
   Имя ключа	Обязательно, до 60 символов («deploy server», «backup script»).
   Что разрешено этому ключу	Отметьте нужные scopes — как минимум один. Ключу только для чтения не следует давать разрешения на запись. Будьте осторожны со scopes, которые влекут списание средств или удаление данных.
   Expiry	Бессрочно, 30 дней, 90 дней или 1 год (API принимает от 1 до 3650 дней).
   Разрешить вызовы только с этих IP	Один IP-адрес или диапазон CIDR на строку, до 20 (IPv4 или IPv6). Пустое значение означает любой IP. По возможности всегда указывайте IP-адрес своего сервера.

4. Подтвердите форму. Ключ отображается один раз в окне «Key created — shown ONCE». Скопируйте его и нажмите I saved the key. Сохраняется только хеш SHA-256, поэтому даже администратор не сможет просмотреть его снова; в случае утери отзовите ключ и создайте новый.

5. В портале также отображается готовая команда curl для проверки ключа.

Ключ выглядит как vk_ с последующей длинной случайной строкой. В списке отображаются только первые символы (например, vk_a1b2c3d4), scopes, срок действия, время последнего использования, количество запросов и статус (Active, Expired, Revoked).

Редактирование, отзыв, аудит

• Edit позволяет изменить имя, скоупы, разрешенные IP-адреса и срок действия. Действие недоступно во время сеанса имперсонации.
• Revoke немедленно отзывает ключ без возможности отмены. Запись сохраняется, чтобы журнал использования оставался доступным.
• Key usage log отображает команды записи и все ошибки за последние 60 дней: время, запрос, ключ, результат и исходный IP-адрес.
• По умолчанию в аккаунте может быть не более 10 активных ключей.
• Ключи, созданные через CLI или вход по MCP, отображаются в разделе Connected apps & devices и могут быть отозваны там же.

Скоупы

Имена скоупов имеют формат area:action. Список доступных зависит от подключенных у вас продуктов.

Скоуп	Разрешает
catalog:read	Чтение тарифных планов и каталога.
vm:read	Просмотр виртуальных машин, метрик и счетов за ВМ.
vm:write	Управление питанием, базовые изменения, фаервол, быстрые Snapshots.
vm:create	Создание ВМ (платно).
vm:plan	Смена тарифа или изменение размера (платно).
vm:destroy	Удаление ВМ.
vm:restore	Восстановление ВМ из Snapshots (перезаписывает диск).
vm:console	Открытие тикетов VNC-консоли.
sshkey:read, sshkey:write	Чтение, добавление и удаление SSH Keys.
volume:read, volume:write, volume:create, volume:destroy	Диски данных (создание и расширение платны; удаление ведет к потере данных).
backup:read, backup:write, backup:restore	Backups (восстановление перезаписывает диск).
billing:read	Кошелек, счета, история платежей — только чтение.
bandwidth:buy	Покупка дополнительного трафика (платно).
account:read, account:write	Профиль, обзор, активность, уведомления; account:write только отмечает уведомления как прочитанные.
apikey:read	Просмотр списка ключей аккаунта и журнала использования (без создания, изменения и отзыва).
apikey:self	По умолчанию для каждого ключа: проверка вызывающего ключа (GET /v1/apikeys/self).
ticket:read, ticket:write	Тикеты техподдержки.
aff:read, transfer:read	Партнерская программа и трансфер услуг — только чтение.
k8s:read, k8s:write, k8s:create, k8s:scale, k8s:destroy, k8s:kubeconfig	Kubernetes (создание и масштабирование платны; kubeconfig с правами cluster-admin).
vpc:read, vpc:write, vpc:create, vpc:destroy	Private Cloud.
image:read, image:write	Образы ОС и ISO (хранилище тарифицируется почасово).
s3:read, s3:write, s3:create, s3:destroy, s3:keys	Object Storage (секрет S3 отображается только один раз).
vpn:read, vpn:detail, vpn:write, vpn:create, vpn:destroy	VPN и прокси IPv6 (данные подключения включают пароли прокси).
dedicated:read, dedicated:write, dedicated:console, dedicated:create, dedicated:destroy	Выделенные серверы (создание списывает средства с кошелька; удаление переустанавливает ОС).
shield:read, shield:write, shield:agent	DDoS Shield, только если модуль включен.

Вызов за пределами скоупов ключа возвращает ответ 403 scope_required; путь, который не разрешено вызывать ни одному ключу, возвращает 403 endpoint_not_public.

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

Ни один скоуп не позволяет: пополнять баланс или выводить средства, изменять привязанные карты или автопополнение, менять пароль, e-mail или 2FA, удалять аккаунт, создавать, изменять или отзывать другие ключи. Для этих действий всегда требуется авторизованная сессия в браузере. Даже в случае утечки ключ не позволит получить доступ к средствам или аккаунту клиента.

Правила, на которые можно положиться

Правило	Описание
Привязка к сайту	Ключ работает только на том сайте (домене), где он был создан.
Лимиты запросов	Для ключа и для аккаунта: по умолчанию 120 и 300 запросов в минуту соответственно.
Идемпотентность	Платные или неповторяемые операции требуют заголовка Idempotency-Key.
Квоты	На ключ распространяются те же квоты, что и на клиента.
Блокировка аккаунта	Ключи заблокированного клиента перестают работать (403 account_blocked).
Аудит	Отзыв ключа администратором записывается в журнал аудита администратора.

Представление администратора

1. Перейдите в Customers › API keys (/customers/apikeys). В таблице отображаются имя и первые символы ключа, владелец, области доступа, статус, последнее использование (время, количество запросов, IP) и срок действия.
2. Фильтруйте по сайту, если у вас есть реселлеры. Ищите по имени, ID или первым символам ключа.
3. Нажмите Revoke, чтобы отозвать активный ключ, или Log для просмотра журнала его использования.
4. Администраторы видят и отзывают ключи, но не могут просматривать их полностью или создавать их для клиентов.

Проверка

1. Создайте ключ только с областью доступа vm:read.
2. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" возвращает список ВМ.
3. curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX" возвращает ответ 403 scope_required.
4. Отозовите ключ; теперь первый вызов возвращает 401 key_revoked.

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

• Ключ больше никогда не отображается. Относитесь к нему как к паролю и сохраните в менеджере секретов или в секретах CI.
• Рекомендуется использовать один ключ на скрипт, минимальные области доступа, короткий срок действия и белый список IP; выполняйте ротацию, создавая новый ключ и отзывая старый.
• Срок действия ключей при входе с устройства (CLI, MCP) по умолчанию составляет 90 дней.
• Отзыв ключа не влияет на удаленные или переданные ресурсы.

Устранение неполадок

Симптом	Причина	Решение
Ошибка too_many_keys (422)	Достигнут лимит активных ключей (по умолчанию 10)	Отозовите старый ключ.
Ошибка invalid_argument: не выбрана область доступа	Не отмечена ни одна область доступа	Отметьте хотя бы одну область доступа.
Ошибка invalid_argument в разрешенных IP	Запись не является IP-адресом или диапазоном, указана неверная длина префикса или задано более 20 записей	Один IP или CIDR на строку, например 203.0.113.0/24.
Создание отклонено при олицетворении	impersonate_forbidden	Попросите клиента создать ключ.
401 key_expired	Истек срок действия	Создайте новый ключ.
401 key_ip_denied	IP-адрес источника запроса не входит в список разрешенных	Добавьте этот IP или очистите список.
401 api_keys_disabled	Функция отключена	Обратитесь к администратору (настройка api_keys_enabled).