## Создать API-ключ

`POST /v1/keys`

Создаёт личный API-ключ на указанном портале от имени владельца менеджмент-ключа. Поля передаются плоско в корне JSON.

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `portalId` | string | да | Идентификатор портала. Список: [`GET /v1/portals`](/docs/management-keys/portals). Владелец менеджмент-ключа должен состоять в этом портале |
| `name` | string | да | Название ключа, до 255 символов. Строка только из пробелов не принимается |
| `scopes` | array | да | [Скоупы](/docs/scopes) нового ключа, хотя бы один. Без `exactScopes: true` к ним добавляются четыре платформенных права — см. ниже |
| `exactScopes` | boolean | нет | `true` — сохранить ровно перечисленные права, без четырёх платформенных. По умолчанию `false` |
| `mode` | string | нет | Режим доступа ключа: `READWRITE` или `READONLY`. Без поля действует режим новых ключей, заданный на портале |
| `ipWhitelist` | array | нет | Разрешённые IP-адреса. Без поля или с пустым массивом — без ограничения |
| `expiresAt` | string \| null | нет | Дата окончания срока действия (ISO 8601). Без поля или `null` — бессрочный |
| `rateLimit` | number \| null | нет | Принимается только `null`. Число от 1 до 100 000 отклоняется с `403 RATE_LIMIT_ADMIN_ONLY`, число вне этого диапазона — с `400 VALIDATION_ERROR` |
| `billing` | string | нет | Принимается только `wallet`, оно же значение по умолчанию. Ключи, оплачиваемые подпиской Cowork/Code, выдаются в кабинете платформы Вайбкод — см. [Свой агент на подписке](/docs/cowork/harness) |

К запрошенным правам добавляются четыре платформенных: `vibe:infra`, `vibe:ai`, `vibe:search`, `vibe:storage`. Ключ из примеров ниже получит `crm`, `task` и эти четыре.

На портале, где администратор выключил работу с серверами, `vibe:infra` из этого набора снимается без ошибки — ключ выпускается с остальными тремя. Отказ `403 INFRA_DISABLED_FOR_PORTAL` приходит только на право, явно перечисленное в `scopes`.

Нужен ключ ровно с перечисленными правами — передайте `exactScopes: true`. Тело `{"portalId": "…", "name": "Только хранилище", "scopes": ["crm", "vibe:storage"], "exactScopes": true}` выпустит ключ только с `crm` и `vibe:storage`, и на `POST /v1/infra/servers` и вызовы AI он ответит `403`. Права такого ключа окончательные: платформа не расширяет их во время запросов, поэтому [`GET /v1/me`](/docs/keys-auth/me) вернёт ровно то, что сохранено при выпуске.

Права `placement`, `entity` и `userfieldtype` личному ключу недоступны и не сохраняются: у созданного ключа их не будет в `scopes` ответа, даже если они были в запросе рядом с правами на данные. Право `userfieldconfig` сохраняется.

## Примеры

Запрос принимает только менеджмент-ключ — см. [Ограничения](/docs/management-keys#ограничения).

### curl — менеджмент-ключ

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/keys" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
    "name": "Выгрузка сделок",
    "scopes": ["crm", "task"]
  }'
```

### JavaScript — менеджмент-ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/keys', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    portalId: '0d9f7744-f853-47c7-b06e-6f61f9dd1b7f',
    name: 'Выгрузка сделок',
    scopes: ['crm', 'task'],
  }),
})

const { success, data } = await res.json()
// Значение ключа приходит один раз — сохраните его в хранилище секретов
const apiKey = data.rawKey
console.log('Создан ключ:', data.id, data.scopes)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.id` | string | Идентификатор записи ключа. Его принимают [`GET /v1/keys/:id`](/docs/management-keys/get), [`PATCH /v1/keys/:id`](/docs/management-keys/update), [`DELETE /v1/keys/:id`](/docs/management-keys/delete) и [`POST /v1/keys/:id/rotate`](/docs/management-keys/rotate) |
| `data.name` | string | Название ключа |
| `data.type` | string | Тип записи ключа, всегда `APP` |
| `data.userId` | string | Идентификатор владельца ключа — владельца менеджмент-ключа |
| `data.portalId` | string | Идентификатор портала |
| `data.clientId` | string \| null | Идентификатор клиента OAuth, если он записан на ключе. Иначе `null` |
| `data.scopes` | array | [Скоупы](/docs/scopes), сохранённые на ключе: запрошенные вместе с добавленными платформенными, без недоступных личному ключу |
| `data.ipWhitelist` | array | Разрешённые IP-адреса. Пустой массив — без ограничения |
| `data.expiresAt` | string \| null | Дата окончания срока действия (ISO 8601), `null` — бессрочный |
| `data.rateLimit` | number \| null | Индивидуальный лимит запросов к AI-эндпоинтам, `null` — общий лимит платформы |
| `data.status` | string | Статус ключа, у нового ключа `ACTIVE` |
| `data.lastUsedAt` | string \| null | Дата последнего запроса этим ключом (ISO 8601), у нового ключа `null` |
| `data.createdAt` | string | Дата создания (ISO 8601) |
| `data.updatedAt` | string | Дата последнего изменения (ISO 8601) |
| `data.accessMode` | string | `READWRITE` или `READONLY` |
| `data.totalDefault` | boolean \| null | Приходит ли `meta.total` в списках, запрошенных этим ключом. `null` — действует настройка платформы |
| `data.issuedVia` | string \| null | Канал, которым выписан вебхук ключа: `per-portal` и `cloud-shared` — модуль-коннектор на портале, `dev_key` — ключ разработчика владельца, `legacy` — регистрация через Битрикс24 Network, `none` — вебхук не заводился, у ключа только права `vibe:*` |
| `data.rawKey` | string | Полное значение ключа. Приходит только в этом ответе — сохраните его сразу |

## Пример ответа

```json
{
  "success": true,
  "data": {
    "id": "3c1f6a52-8e4b-4d07-9a1e-5b2d7f0c6e91",
    "name": "Выгрузка сделок",
    "type": "APP",
    "userId": "fafa9780-eed7-4d29-b040-2448d924f452",
    "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
    "clientId": null,
    "scopes": ["crm", "task", "vibe:infra", "vibe:ai", "vibe:search", "vibe:storage"],
    "ipWhitelist": [],
    "expiresAt": null,
    "rateLimit": null,
    "status": "ACTIVE",
    "lastUsedAt": null,
    "createdAt": "2026-10-29T12:23:14.701Z",
    "updatedAt": "2026-10-29T12:23:14.701Z",
    "accessMode": "READWRITE",
    "totalDefault": null,
    "issuedVia": "cloud-shared",
    "rawKey": "vibe_api_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}
```

## Пример ответа при ошибке

400 — не передан `portalId`:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_PORTAL_ID",
    "message": "Field portalId is required"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `MISSING_PORTAL_ID` | В теле запроса не указан `portalId` |
| 400 | `VALIDATION_ERROR` | Тело не прошло проверку: нет `name` или `scopes`, пустой `scopes`, неизвестное право, некорректный IP-адрес или дата. Поле и причина — в `error.message` |
| 400 | `INVALID_JSON_BODY` | Тело запроса — некорректный JSON |
| 400 | `BILLING_MODE_NOT_SUPPORTED` | В теле передано `billing: "subscription"` |
| 400 | `PERSONAL_KEY_WEBHOOK_SCOPES_INVALID` | В `scopes` нет ни одного права на данные. Личный ключ выписывается входящим вебхуком Битрикс24, а права `placement`, `entity` и `userfieldtype` требуют контекста приложения и личному ключу недоступны. Добавьте хотя бы одно право на данные, например `crm` или `user_brief`, либо заведите OAuth-приложение для возможностей приложения |
| 400 | `INVALID_SCOPES` | Часть запрошенных прав недоступна на аккаунте Битрикс24 |
| 400 | `PORTAL_NOT_LINKED` | Портал не подключён к Битрикс24 Network — создать ключ невозможно |
| 400 | `BOX_NO_DEVELOPER_KEY` | Портал коробочный, у владельца не настроен ключ разработчика, а в `scopes` есть права Битрикс24 |
| 402 | `MARKETPLACE_REQUIRED` | На портале нет активной подписки BitrixGPT + Маркетплейс. Приходит только там, где доступ к платформе открывает подписка. Условия и ссылка на оформление — в `error.details` и `error.userMessage` |
| 402 | `BY_PAID_ONLY` | Доступ открывает платный или демо-тариф Битрикс24. Открывает его и платная подписка Битрикс24 Маркет Плюс — в Беларуси она продаётся |
| 402 | `KZ_PAID_ONLY` | Регион портала открывает доступ по тарифу: платный или демо-тариф Битрикс24, подписка в регионе не продаётся |
| 402 | `UZ_PAID_ONLY` | То же для региона UZ: платный или демо-тариф Битрикс24, подписка в регионе не продаётся |
| 402 | `INT_TARIFF_REQUIRED` | Портал международного сегмента на бесплатном тарифе Битрикс24 |
| 402 | `SELFHOSTED_NOT_AVAILABLE` | Портал коробочный, а коробочный Битрикс24 на этой установке пока не обслуживается. Покупка тарифа отказ не снимает, обращаться — в поддержку |
| 402 | `B24_PAID_TARIFF_REQUIRED` | Тариф Битрикс24 на портале бесплатный, а на таком тарифе Битрикс24 закрывает REST при любом состоянии подписки BitrixGPT + Маркетплейс. Поле `error.userMessage` называет условие доступа. Помогает только переход портала на платный тариф Битрикс24, ссылки на покупку — в `error.details.upgradeUrl` и `error.details.secondaryUpgradeUrl`, когда портал их отдаёт. Тариф «Демо» не затронут |
| 402 | `ACCOUNT_FROZEN` | Платёжный аккаунт портала заморожен за отрицательный баланс |
| 403 | `NOT_PORTAL_MEMBER` | Владелец менеджмент-ключа не состоит в портале с указанным `portalId` |
| 403 | `PORTAL_ACCESS_BLOCKED` | Доступ владельца к порталу отключён: его участие в портале неактивно или запрещено политикой доступа портала |
| 403 | `PORTAL_TARIFF_UNREADABLE` | Состояние тарифа аккаунта сейчас подтвердить не удалось. Причина может быть временной (занята очередь проверок, недавняя попытка, истёк отведённый на проверку срок) или в правах ключа. Повторите проверку в кабинете платформы Вайбкод: менеджмент-ключ не привязан к порталу, поэтому `/v1/me?refresh=tariff` с ним проверку не запускает (запрос с уже существующим ключом нужного аккаунта запускает). Поле `error.details.requiredTariffs` пустое, покупка не предлагается. Переподключение под главным администратором аккаунта и обращение в поддержку нужны, только если повторная проверка стабильно не помогает |
| 403 | `PORTAL_SUBSCRIPTION_UNREADABLE` | Состояние подписки аккаунта сейчас подтвердить не удалось. Причина может быть временной (занята очередь проверок, недавняя попытка, истёк отведённый на проверку срок) или в правах ключа. Повторите проверку в кабинете платформы Вайбкод: менеджмент-ключ не привязан к порталу, поэтому `/v1/me?refresh=tariff` с ним проверку не запускает (запрос с уже существующим ключом нужного аккаунта запускает). Поле `error.details.requiredTariffs` пустое, покупка не предлагается. Переподключение под главным администратором аккаунта и обращение в поддержку нужны, только если повторная проверка стабильно не помогает |
| 403 | `KEY_CREATION_RESTRICTED` | Политика портала не разрешает владельцу создавать ключи. Право выдаёт администратор портала — см. [Права на создание](/docs/access-rights) |
| 403 | `KEY_POLICY_READONLY_REQUIRED` | Политика портала разрешает создавать только ключи с режимом `READONLY`, а в `mode` запрошен `READWRITE` |
| 403 | `RATE_LIMIT_ADMIN_ONLY` | В `rateLimit` передано число. Индивидуальный лимит через этот эндпоинт не задаётся |
| 403 | `INFRA_DISABLED_FOR_PORTAL` | В `scopes` явно запрошено право `vibe:infra`, а администратор портала выключил работу с серверами. Ключ не создаётся. Запрос без этого права проходит и на закрытом портале |
| 403 | `SCOPE_NOT_AVAILABLE_ON_PORTAL` | В `scopes` есть право, которое на этом портале не включено. Список таких прав — в `error.message` |
| 403 | `ONEC_ACCESS_REQUIRED` | В `scopes` запрошено право `vibe:onec`, а у владельца ключа нет доступа к 1С. Доступ к 1С выдаёт администратор портала. Ключ не создаётся. Если проверить доступ не удалось, право выдаётся |
| 403 | `KEY_STORAGE_SCOPE_REQUIRES_PERSONAL_KEY` | В `scopes` явно запрошено право `vibe:storage`, а менеджмент-ключ не подтверждён как личный ключ владельца. Отказ приходит и с `exactScopes: true`. Менеджмент-ключ, созданный в личном кабинете, этот отказ не получает |
| 403 | `B24_MARKET_SUBSCRIPTION_REQUIRED` | На аккаунте нет действующей подписки маркетплейса, и вебхук не выписывается. Ссылка на оформление — в `error.details.upgradeUrl`. На облачном аккаунте с прочитанным бесплатным тарифом Битрикс24 этот код не приходит: там отвечает `B24_PAID_TARIFF_REQUIRED`. Коробочный аккаунт эта замена не затрагивает |
| 403 | `B24_MARKET_TRIAL_USED` | Пробный период подписки маркетплейса израсходован — нужна платная подписка. Ссылка на оформление — в `error.details.upgradeUrl`. На облачном аккаунте с прочитанным бесплатным тарифом Битрикс24 этот код не приходит: там отвечает `B24_PAID_TARIFF_REQUIRED`. Коробочный аккаунт эта замена не затрагивает |
| 403 | `INT_TARIFF_REQUIRED` | Тот же отказ по подписке в регионе, где доступ определяется платным тарифом Битрикс24. Ссылки на оформление нет: подписка там не продаётся |
| 403 | `B24_INSUFFICIENT_SCOPE` | Ключу разработчика владельца не хватает прав на аккаунте. Переподключите аккаунт, чтобы ключ разработчика выписался заново |
| 403 | `B24_ACCESS_DENIED` | Битрикс24 не выдал вебхук по правам сотрудника |
| 403 | `CONNECTOR_KEY_ISSUE_FORBIDDEN` | Аккаунт запрещает этому сотруднику выписывать ключи. Право выдаёт администратор аккаунта — см. [Права на создание](/docs/access-rights) |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Менеджмент-ключ в режиме «только чтение» |
| 403 | `MANAGEMENT_SCOPE_REQUIRED` | У менеджмент-ключа нет скоупа `vibe:mgmt:keys` |
| 409 | `CONNECTOR_MODULE_NOT_INSTALLED` | Модуль-коннектор на аккаунте не установлен, выписать ключ через него нельзя. Повтор без установки модуля не поможет |
| 410 | `STALE_DEVELOPER_KEY` | Ключ разработчика владельца недействителен и автоматически не перевыпускается. Переподключите аккаунт |
| 502 | `CONNECTOR_PLAN_REQUIRED` | Тариф аккаунта Битрикс24 не включает Вайбкод, и предлагать нечего — коробочный аккаунт, аккаунт уже на платном тарифе, нераспознанный регион. Текст причины для человека — в `error.userMessage`. Повтор не поможет, пока тариф не сменён |
| 502 | `CONNECTOR_REST_UNAVAILABLE` | Битрикс24 отказал в выписке, а управляемого решения нет: подписка или пробный период аккаунта по данным платформы действуют. Исходная причина — в `error.details.reason`, `error.details.retryable: true` говорит, что состояние временное. Предложения оформить подписку в ответе нет: оформлять нечего. Свежее чтение подписки перед ответом платформа не гарантирует |
| 502 | `CONNECTOR_KEY_ISSUE_FAILED` | Другой отказ модуля-коннектора или недоступность его транспорта. Исходная причина — в `error.details.reason` |
| 502 | `CONNECTOR_KEY_ISSUE_RESPONSE_LOST` | Ответ модуля-коннектора потерян, и вебхук на портале мог уже появиться. Не повторяйте выписку сразу |
| 502 | `RECOVERY_FAILED` | Перевыпуск ключа разработчика не удался, состояние временное — повторите запрос |
| 502 | `DEVKEY_MINT_FAILED` | Другой отказ выписки через ключ разработчика. Диагностика — в `error.details.b24Code` и `error.details.b24Status` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 не зарегистрировал входящий вебхук: не ответил или отказал без названной причины. Во втором случае ответ несёт `error.details.incidentCode` — шестисимвольный код обращения, по которому поддержка находит запись в журнале |
| 503 | `NETWORK_DEVKEY_REQUIRED` | Ключ разработчика владельца ещё не выдан, а выписка на этом портале идёт только через него. Текст для человека — в `error.userMessage` |
| 503 | `CONNECTOR_KEY_ISSUE_TIMEOUT` | Модуль-коннектор не ответил вовремя, и вебхук на портале мог уже появиться. Не повторяйте выписку сразу |
| 401 | `WRONG_KEY_TYPE` | Запрос отправлен ключом портала — личным `vibe_api_` или ключом авторизации `vibe_app_`. Эндпоинт принимает только менеджмент-ключ |
| 401 | `KEY_INACTIVE` | Менеджмент-ключ отозван или заблокирован |
| 401 | `KEY_EXPIRED` | Срок действия менеджмент-ключа закончился |
| 401 | `INVALID_API_KEY` | Ключ с переданным значением не найден |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |

Отказы `OWNER_DELETED`, `OWNER_BLOCKED`, `ACCOUNT_PENDING_ERASURE` и `B24_USER_DELETED` зависят от аккаунта владельца ключа — см. [Состояние аккаунта владельца](/docs/management-keys#состояние-аккаунта-владельца).

**Две проверки доступа к платформе.** Первая — проверка доступа портала. Её исходы со статусом `402` — `MARKETPLACE_REQUIRED`, `BY_PAID_ONLY`, `KZ_PAID_ONLY`, `UZ_PAID_ONLY` и `INT_TARIFF_REQUIRED`. Какой именно придёт, решает не регион лицензии сам по себе, а то, чем платформа открывает доступ на этом портале: где его открывает подписка — `MARKETPLACE_REQUIRED`, где тариф Битрикс24 — один из четырёх остальных. `MARKETPLACE_REQUIRED` приходит только тогда, когда подписка прочитана и её нет. Коробочный портал там, где коробочный Битрикс24 пока не обслуживается, получает `402 SELFHOSTED_NOT_AVAILABLE`. Ещё два исхода той же проверки идут со статусом `403`, и оба означают, что платформе нечего назвать: `PORTAL_TARIFF_UNREADABLE` и `PORTAL_SUBSCRIPTION_UNREADABLE`. Эта проверка касается только выписки нового ключа: [перевыпуск](/docs/management-keys/rotate), автоматическое восстановление ключа и передача владения ей не подчиняются, а уже выданные ключи продолжают работать.

Вторая проверка идёт позже, и область у неё шире: сам Битрикс24 отказывает в выписке, потому что тариф аккаунта не включает Вайбкод. Она срабатывает на всём, что выписывает ключ, — на создании, на [перевыпуске](/docs/management-keys/rotate), на автоматическом восстановлении ключа и на передаче владения. Там, где доступ продаётся, ответ — `402` с кодом `BY_PAID_ONLY`, `KZ_PAID_ONLY` или `UZ_PAID_ONLY`. Где предлагать нечего — `502 CONNECTOR_PLAN_REQUIRED`. Повтор запроса с любым из этих кодов не поможет, пока тариф Битрикс24 не сменён.

**Отказы, общие с перевыпуском.** Отказы самой выписки приходят и на перевыпуске — какие именно, перечислено в [Перевыпустить API-ключ](/docs/management-keys/rotate#ошибки). Тело отказа выписки может нести поле `error.reason` с точной причиной во внутренней классификации платформы, тогда как `error.code` остаётся прежним. Разбирайте отказ по `error.code`, а не по тексту `message`.

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Смотрите также

- [Список API-ключей портала](/docs/management-keys/list)
- [Получить API-ключ](/docs/management-keys/get)
- [Изменить API-ключ](/docs/management-keys/update)
- [Удалить API-ключ](/docs/management-keys/delete)
- [Перевыпустить API-ключ](/docs/management-keys/rotate)
- [Список порталов](/docs/management-keys/portals)
- [Скоупы](/docs/scopes)
- [Менеджмент-ключи](/docs/management-keys)