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

POST /v1/keys

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

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

К запрошенным правам добавляются четыре платформенных: 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 вернёт ровно то, что сохранено при выпуске.

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

Примеры

Запрос принимает только менеджмент-ключ — см. Ограничения.

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

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 — менеджмент-ключ

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": 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:

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

Ошибки

Отказы OWNER_DELETED, OWNER_BLOCKED, ACCOUNT_PENDING_ERASURE и B24_USER_DELETED зависят от аккаунта владельца ключа — см. Состояние аккаунта владельца.

Две проверки доступа к платформе. Первая — проверка доступа портала. Её исходы со статусом 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. Эта проверка касается только выписки нового ключа: перевыпуск, автоматическое восстановление ключа и передача владения ей не подчиняются, а уже выданные ключи продолжают работать.

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

Отказы, общие с перевыпуском. Отказы самой выписки приходят и на перевыпуске — какие именно, перечислено в Перевыпустить API-ключ. Тело отказа выписки может нести поле error.reason с точной причиной во внутренней классификации платформы, тогда как error.code остаётся прежним. Разбирайте отказ по error.code, а не по тексту message.

Полный список общих ошибок API — Ошибки.

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

• Список API-ключей портала
• Получить API-ключ
• Изменить API-ключ
• Удалить API-ключ
• Перевыпустить API-ключ
• Список порталов
• Скоупы
• Менеджмент-ключи