---
title: Ключи API и области доступа
description: Как клиенты создают ключи API (префикс vk_), задают scopes, ограничивают их по IP и сроку действия, а администраторы просматривают и отзывают их.
url: https://nexcmp.com/ru/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Ключи API и области доступа {#api-keys-and-scopes}

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

## Назначение {#what-it-does}

**API key** позволяет скрипту, задаче CI, [`cmp` CLI](https://nexcmp.com/ru/docs/developers/cmp-cli/) или ИИ-ассистенту ([MCP](https://nexcmp.com/ru/docs/developers/mcp/)) вызывать [REST API](https://nexcmp.com/ru/docs/developers/api/) от имени конкретного клиента с предоставленными правами (**scopes**). Клиентские ключи начинаются с `vk_`. Они могут читать и управлять сервисами, но **никогда** не имеют доступа к деньгам или самой учетной записи.

## Требования {#requirements}

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

## Создание ключа (клиент) {#create-a-key-customer}

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-revoke-audit}

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

## Скоупы {#scopes}

Имена скоупов имеют формат `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`**.

### Что никогда не может делать ключ {#what-a-key-can-never-do}

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

## Правила, на которые можно положиться {#rules-you-can-rely-on}

| Правило | Описание |
|---|---|
| Привязка к сайту | Ключ работает только на том сайте (домене), где он был создан. |
| Лимиты запросов | Для ключа и для аккаунта: по умолчанию 120 и 300 запросов в минуту соответственно. |
| Идемпотентность | Платные или неповторяемые операции требуют заголовка `Idempotency-Key`. |
| Квоты | На ключ распространяются те же [квоты](https://nexcmp.com/ru/docs/billing/quotas/), что и на клиента. |
| Блокировка аккаунта | Ключи заблокированного клиента перестают работать (403 `account_blocked`). |
| Аудит | Отзыв ключа администратором записывается в журнал аудита администратора. |

## Представление администратора {#administrator-view}

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

![Список API-ключей клиентов для администратора с областями доступа, статусом, последним использованием и кнопкой Revoke](https://nexcmp.com/ru/docs/images/developers/api-keys-02-admin.webp)

## Проверка {#verify}

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`.

## Ограничения и примечания {#limits-notes}

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

## Устранение неполадок {#troubleshooting}

| Симптом | Причина | Решение |
|---|---|---|
| Ошибка `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`). |