#Создание и использование ключа

Ключ — это учётные данные для доступа к Vibe API. Эта страница проводит через создание ключа в личном кабинете шаг за шагом и разбирает каждый параметр формы: название, скоупы, срок действия, лимит запросов и список разрешённых IP.

Какие скоупы выбрать под задачу — на отдельной странице Скоупы.

#Типы ключей

API-ключ (vibe_api_). Создаётся в личном кабинете и привязан к одному порталу Битрикс24. Все запросы идут от лица владельца ключа, токен сессии не требуется. Подходит для личных дашбордов, скриптов, серверных интеграций и ботов на своём портале.

Ключ авторизации (vibe_app_). Привязан к Вайбкод-приложению с OAuth-учётными данными Битрикс24. Каждый запрос отправляется от лица пользователя, установившего приложение и прошедшего авторизацию, — поэтому нужен заголовок Authorization: Bearer. Подходит для приложений из каталога, которые работают на разных порталах под разными пользователями. Этот же ключ нужен, чтобы приложение открывалось внутри Битрикс24 — в левом меню, вкладке CRM или виджете (раздел Встраивание приложения в портал).

Менеджмент-ключ (vibe_live_). Не привязан к одному порталу, предназначен для администрирования: управления ключами, просмотра порталов, работы с обратной связью. Доступа к данным сущностей Битрикс24 не имеет. Полное описание — Менеджмент-ключи.

Дальше — создание обоих ключей портала: API-ключа (vibe_api_) и ключа авторизации (vibe_app_). Формы немного отличаются, отличие описано ниже. Менеджмент-ключ (vibe_live_) описан отдельно — Менеджмент-ключи.

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

1. Войдите в личный кабинет.
2. Откройте раздел Ключи API.
3. Нажмите Создать.
4. Заполните форму (шаги ниже).
5. Скопируйте ключ — он показывается один раз.

#Шаг 1. Название

Произвольное название для самого себя — по нему ключ виден в списке. На доступ не влияет. Заведите отдельный ключ с понятным названием для каждого сервиса или интеграции — это упрощает отзыв при компрометации.

#Шаг 2. Скоупы

Скоупы — это разрешения на доступ к данным. В форме они сгруппированы во вкладки «Битрикс24» и «Вайбкод»; нужно отметить минимум один.

Полный список скоупов, описание каждого и подбор набора под задачу — на странице Скоупы. Короткий ориентир: crm — данные CRM, tasks — задачи, imbot + im — чат-бот, disk — файлы.

Четыре скоупа платформы (vibe:infra, vibe:ai, vibe:search, vibe:storage) добавляются к ключу автоматически — отмечать их не нужно.

Набор скоупов Битрикс24 закрепляется за ключом в момент выпуска. Если добавить скоуп Битрикс24 в настройках уже существующего ключа, GET /v1/me покажет его в списке, но запросы, которым он нужен, вернут BITRIX_ACCESS_DENIED: к данным Битрикс24 ключ обращается с тем набором скоупов, с которым был выпущен. Чтобы выдать ключу новый скоуп Битрикс24:

• API-ключ (vibe_api_) — перевыпустите ключ или создайте новый с отмеченным скоупом.
• Ключ авторизации (vibe_app_) — создайте приложение заново с нужным скоупом и пройдите авторизацию заново (перевыпуск ключа здесь скоуп не выдаёт).

Скоуп выдаётся при выпуске только если он доступен на портале Битрикс24. Если после перевыпуска или повторной авторизации вызов всё ещё возвращает BITRIX_ACCESS_DENIED, значит скоуп для этого ключа на портале не предоставлен.

#Шаг 3. Срок действия

Когда ключ перестанет действовать. Варианты: без ограничения, 30, 90, 180 или 365 дней. После истечения срока запросы с ключом отклоняются с кодом KEY_EXPIRED. Для серверных интеграций задавайте конечный срок и обновляйте ключ заранее.

#Шаг 4. Лимит запросов

Необязательный индивидуальный лимит для этого ключа. Если поле пустое — применяются общие лимиты платформы и портала (раздел «Лимиты запросов» ниже). Значение, действующее для ключа, возвращает GET /v1/me в поле rateLimit.requestsPerSecond.

#Шаг 5. Список разрешённых IP

В блоке «Расширенные настройки». Ограничивает вызовы ключа списком IP-адресов. Поддерживаются точные адреса IPv4 и IPv6, по одному в строке; подсети в формате CIDR не поддерживаются.

192.168.1.100
203.0.113.42
2001:db8::1

Запрос с адреса вне списка отклоняется с кодом 403 IP_NOT_ALLOWED. Если список пуст — ограничения по IP нет.

#Шаг 6. Сохраните ключ

Полный ключ показывается один раз сразу после создания. Скопируйте и сохраните его в надёжном месте — повторно его получить нельзя, только перевыпустить.

#Создание ключа авторизации

Ключ авторизации (vibe_app_) создаётся в разделе Ключи авторизации личного кабинета. Форма короче, чем у API-ключа: всего два поля.

1. Откройте раздел Ключи авторизации и нажмите Создать.
2. Название — под ним приложение видно в списке.
3. Скоупы — те же две группы «Битрикс24» и «Вайбкод», минимум один; подбор набора описан на странице Скоупы.
4. Скопируйте ключ — он показывается один раз.

Срок действия, лимит запросов и список разрешённых IP в этой форме не задаются — этим она и отличается от формы API-ключа. После создания ключ авторизации работает в паре с токеном сессии: каждый запрос отправляется с заголовками X-Api-Key и Authorization: Bearer (раздел «Передача ключа»).

#Встраивание приложения в портал

Если приложение должно открываться внутри Битрикс24 — пунктом в левом меню, вкладкой в карточке CRM или виджетом на рабочем столе, — для этого нужен ключ авторизации (vibe_app_). API-ключ (vibe_api_) встраивание в интерфейс портала не поддерживает: с ним приложение обращается к данным, но не размещается в окне Битрикс24.

Ключ авторизации даёт две возможности, которых нет у API-ключа:

• Размещение в интерфейсе. Приложение появляется в выбранном месте портала — за это отвечает привязка размещения POST /v1/placements/bind. Доступные места возвращает GET /v1/placements/available.
• Прозрачная авторизация. Пользователь открывает приложение внутри Битрикс24 без отдельного входа: Gateway сам определяет, кто открыл приложение, и передаёт его данные серверу приложения. Браузер токен сессии не видит.

Порядок действий:

1. Создайте ключ авторизации в разделе Ключи авторизации — форма описана выше в разделе «Создание ключа авторизации».
2. Передайте AI-модели именно ключ авторизации (vibe_app_) и попросите приложение со встраиванием в портал.
3. Модель вызовет GET /v1/me с этим ключом и получит раздел placements с полным порядком встраивания.

Полный жизненный цикл встроенного приложения, BFF-паттерн (Backend-for-Frontend) и скелеты обработчика на Node, Python и Go — Авторизация в приложении на BlackHole.

#Передача ключа

Ключ передаётся в заголовке X-Api-Key:

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/deals

Клиенты, которые умеют отправлять только Authorization: Bearer (например, OpenAI-совместимые), могут передать сам API-ключ (vibe_api_…) в этом заголовке вместо X-Api-Key — для ключа оба заголовка равнозначны. Это работает на всех V1-эндпоинтах, включая бот-платформу:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/bots

У ключа авторизации (vibe_app_…) заголовок Authorization: Bearer занят токеном сессии, поэтому сам ключ всегда идёт в X-Api-Key (см. ниже).

Для ключа авторизации (vibe_app_) дополнительно передаётся токен сессии в заголовке Authorization: Bearer:

curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/deals

Если для ключа vibe_app_ не передан Authorization: Bearer, эндпоинты, которым нужен пользовательский контекст, возвращают 401 TOKEN_MISSING: у запроса нет данных, от чьего имени обращаться к Битрикс24. Эндпоинты /v1/me и /v1/oauth/* работают без Bearer.

Токен сессии живёт 24 часа и не обновляется. POST /v1/oauth/token (и GET /v1/oauth/poll) выдают access_token с expires_in: 86400 — без refresh_token и без grant'а обновления. Механизма «тихого» продления нет — это сознательное решение. После истечения 24 часов получите новый токен сессии, заново пройдя OAuth-флоу: GET /v1/oauth/authorize → POST /v1/oauth/token. До истечения вызовы за пользователя возвращают 401 TOKEN_EXPIRED — это сигнал заново авторизоваться.

Для фоновых сценариев — cron, серверные интеграции, скрипты без пользователя у экрана, которому нечем пройти авторизацию заново каждые 24 часа — используйте персональный API-ключ (vibe_api_…): он работает от лица владельца ключа без токена сессии, и единственное ограничение по сроку — собственный «срок действия» ключа (см. выше). Ключ авторизации (vibe_app_…) предназначен для приложений, где пользователь присутствует и проходит OAuth.

Самоописание /v1/me отвечает в двух режимах:

Верхний уровень ответа одинаковый в обоих режимах — отличает только заполненность поля currentUser. Поле capabilities.servers.create.available тоже зависит от режима: для vibe_app_ ключа без сессии возвращается false с причиной SESSION_REQUIRED, потому что инфраструктурные POST-эндпоинты требуют пользовательский контекст.

Эндпоинты создания инфраструктуры (POST /v1/infra/servers, а также POST /api/agents и POST /api/managed-bots через личный кабинет) требуют, чтобы платформа точно знала кто создаёт сервер — это нужно для тарифной проверки и учёта в лимитах. Для ключей vibe_app_ это значит наличие Authorization: Bearer <session>; без сессии ответ — 401 UNAUTHENTICATED с error.hint, в котором указан рабочий вариант (пройти OAuth-флоу или использовать персональный ключ vibe_api_). На чтение (GET /v1/infra/servers, GET /v1/me) сессия не нужна.

#Жизненный цикл ключа

Создание → Активен → Перевыпуск / Отзыв / Удаление

#Состояния ключа

#Перевыпуск

Перевыпуск создаёт новый ключ и оставляет старому переходный период 24 часа — это позволяет обновить ключ в приложениях без простоя:

1. Запустите перевыпуск в личном кабинете.
2. Получите новый ключ.
3. Обновите ключ в своих приложениях.
4. Старый ключ действует ещё 24 часа.
5. По истечении переходного периода старый ключ становится недействительным.

#Отзыв и удаление

Отзыв переводит ключ в состояние REVOKED: последующие запросы отклоняются с 401 KEY_INACTIVE. Если на ключе есть активные серверы, удаление возвращает 409 KEY_HAS_ACTIVE_SERVERS — сначала удалите серверы.

#Если ключ скомпрометирован

1. Отзовите ключ в личном кабинете.
2. Создайте новый ключ с теми же скоупами.
3. Обновите ключ во всех приложениях.
4. Проверьте журнал запросов на обращения с неизвестных адресов.
5. Включите список разрешённых IP.

#Рекомендации по безопасности

• Храните ключи в переменных окружения или менеджере секретов, не в коде и не в git.
• Не передавайте ключи через мессенджеры и почту.
• Назначайте ключу только необходимые скоупы — подбор набора описан на странице Скоупы.
• Заводите отдельный ключ для каждого сервиса и отзывайте неиспользуемые.
• Для серверных интеграций включайте список разрешённых IP и конечный срок действия.
• Перевыпускайте ключи по расписанию (например, раз в 90 дней).

#Технические подробности

Ниже — детали для AI-моделей и продвинутых интеграций.

#Самоописание ключа (`/v1/me`)

GET /v1/me возвращает тип ключа, портал, скоупы, лимиты и карту доступных эндпоинтов. Это основная точка входа для AI-моделей: достаточно передать модели ключ и ссылку https://vibecode.bitrix24.tech/v1/me.

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/me

Ответ для API-ключа (vibe_api_), показаны характерные поля:

{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.ru",
    "scopes": ["crm", "tasks", "user", "vibe:infra", "vibe:ai", "vibe:search", "vibe:storage"],
    "rateLimit": { "requestsPerSecond": 10 },
    "auth": {
      "personalKey": "X-Api-Key: vibe_api_… (no Bearer)",
      "oauthKey": "X-Api-Key: vibe_app_… + Authorization: Bearer <session_token>"
    },
    "owner": { "name": "Иван Петров", "userId": "1" },
    "expiresAt": null
  }
}

Кроме показанных полей ответ содержит разделы api (карта доступных эндпоинтов и сущностей), capabilities, tariff и errorCodes — модель использует их, чтобы построить запросы без чтения остальной документации.

Ответ для ключа авторизации (vibe_app_):

{
  "success": true,
  "data": {
    "type": "oauth_app",
    "portal": "mycompany.bitrix24.ru",
    "scopes": ["crm", "tasks"],
    "app": { "title": "CRM Dashboard", "id": "f2342f7a-…" },
    "oauth": {
      "authorizeUrl": "https://vibecode.bitrix24.tech/v1/oauth/authorize?app_key=vibe_app_…",
      "authorizeUrlNote": "Template URL — append required query params before redirecting the user…",
      "requiredParams": { "state": { "required": true, "minLength": 16, "maxLength": 512 }, "redirect_uri": { "required": false }, "scope": { "required": false } },
      "tokenUrl": "https://vibecode.bitrix24.tech/v1/oauth/token",
      "revokeUrl": "https://vibecode.bitrix24.tech/v1/oauth/revoke"
    },
    "auth": {
      "header": "X-Api-Key: <this-key> + Authorization: Bearer <session-token>",
      "steps": [
        "1. Redirect user to oauth.authorizeUrl + state (+ redirect_uri)",
        "2. Exchange code for session token",
        "3. Call API with both headers"
      ],
      "gatewayInjected": {
        "description": "Для приложения, встроенного в Битрикс24 через placement и работающего за BlackHole, Gateway сам аутентифицирует пользователя и инжектирует заголовок на каждый запрос. Браузер токен не видит.",
        "header": "X-Vibe-Authorization: Bearer vibe_session_*",
        "docs": "https://vibecode.bitrix24.tech/docs/infra/app-runtime"
      }
    }
  }
}

⚠ oauth.authorizeUrl — это шаблон, а не готовая ссылка. Эндпоинт /v1/oauth/authorize требует обязательный параметр state (16–512 символов) — это CSRF-токен по RFC 6749 §10.12, который генерирует клиент: создайте криптослучайную строку, добавьте её в URL и сверьте значение, вернувшееся в callback. Сервер не может сгенерировать state за вас — иначе защита от CSRF не работает. Открытие authorizeUrl как есть вернёт 400 INVALID_REQUEST "state: Required". Опционально добавьте redirect_uri (ваш callback; без него используется встроенная страница /oauth/complete) и scope. Пример полной ссылки:

Копировать

https://vibecode.bitrix24.tech/v1/oauth/authorize?app_key=vibe_app_…&state=aAbBcCdDeEfFgGhH&redirect_uri=https://myapp.com/callback

Структура ответа для менеджмент-ключа отличается — она описана на странице Менеджмент-ключи.

#Полная передача ключа

Ключ можно передать через Authorization: Bearer <vibe_*> без заголовка X-Api-Key — этот вариант поддерживается для OpenAI-совместимых клиентов. При вызове через OAuth-приложение токен сессии в этом случае передать нельзя, поэтому способ применим только к ключам vibe_api_ и vibe_live_.

Для приложения, встроенного в Битрикс24 как placement и работающего за BlackHole, токен сессии не приходит ни в адресе, ни в теле — Gateway сам аутентифицирует пользователя и инжектирует заголовок X-Vibe-Authorization: Bearer vibe_session_* на каждый запрос к серверу приложения. Браузер не видит и не хранит токен (sessionStorage остаётся пустым). Идентификатор пользователя приложение читает одним вызовом GET /v1/me, передавая Authorization: Bearer из заголовка X-Vibe-Authorization: в ответе будет currentUser.bitrixUserId (числовой ID пользователя Битрикс24) и portal (домен портала на верхнем уровне). Полный жизненный цикл запроса, BFF-паттерн (Backend-for-Frontend) и скелеты обработчика на Node/Python/Go — Авторизация в приложении на BlackHole.

#Лимиты запросов

К каждому ключу одновременно применяются две независимые системы лимитов: лимит платформы Вайбкод и лимит портала Битрикс24.

#Лимит платформы Вайбкод

При превышении возвращается 429 Too Many Requests с кодом RATE_LIMITED.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 245
X-RateLimit-Reset: 25

#Лимит портала Битрикс24

Портал ограничивает скорость обращений (по умолчанию около 10 запросов в секунду, лимит делится между всеми ключами портала). При превышении возвращается 502 BITRIX_UNAVAILABLE. Действующее для ключа значение возвращает GET /v1/me в поле rateLimit.requestsPerSecond.

Один вызов считается за единицу. Один POST /v1/batch с 50 операциями расходует одну единицу — это самый экономный способ уложиться в лимит.

#Рекомендации при лимитах

• Объединяйте запросы через POST /v1/batch (до 50 операций за вызов).
• Кэшируйте данные, которые меняются редко.
• При 429 повторяйте запрос с увеличением паузы (1 с → 2 с → 4 с).
• Опирайтесь на заголовки X-RateLimit-*, чтобы не доводить до отказа.

#Коды ошибок ключа

Полный справочник кодов — Коды ошибок.

#Режим доступа

У каждого ключа есть отдельное поле accessMode — оно отвечает за то, разрешает ли ключ запись, или ограничивает его операциями чтения. Это независимая от скоупов настройка: скоупы определяют, к каким разделам данных у ключа есть доступ, а режим доступа — может ли ключ менять эти данные.

#Два режима

Какие вызовы попадают под блокировку в режиме READONLY:

• API-ключи и ключи авторизации (vibe_api_, vibe_app_) — блокируется любой запрос, который проксируется в Битрикс24 как операция записи: создание, обновление, удаление, действия над сущностями. GET-запросы и операции агрегации (POST /v1/<entity>/aggregate) выполняются без ограничений.
• Менеджмент-ключи (vibe_live_) — блокировка идёт по HTTP-методу: POST, PATCH, PUT, DELETE отклоняются, GET и HEAD проходят. Это значит, что менеджмент-ключ в режиме «только чтение» не может создавать новые ключи, менять портал или отправлять обратную связь, но может читать настройки и журнал событий.

Эндпоинт GET /v1/me возвращает действующий режим ключа в поле data.accessMode:

{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.ru",
    "accessMode": "READONLY",
    "scopes": ["crm", "tasks"]
  }
}

#Изменение режима

Владелец ключа меняет режим в личном кабинете в разделе Ключи API:

1. Откройте карточку нужного ключа.
2. В блоке Режим доступа выберите «Только чтение» или «Чтение и запись».
3. Сохраните изменения — режим применяется к следующему запросу.

Перевыпуск не нужен — режим меняется у действующего ключа без замены значения. При создании нового ключа режим задаётся отдельным переключателем в форме.

Администратор портала видит чужие ключи в общем списке и может изменить режим любого ключа на портале. После сохранения владелец получает сообщение от Companion-бота с информацией о том, что режим его ключа был изменён администратором.

#Политика портала по умолчанию

Администратор задаёт режим, который применяется ко всем новым ключам портала. Настройка живёт в разделе Ключи API в блоке «Политика портала по умолчанию» и видна только администраторам.

Возможные значения:

• Чтение и запись (READWRITE) — значение по умолчанию для портала. Любой пользователь создаёт ключи с любым режимом на своё усмотрение.
• Только чтение (READONLY) — обычные участники портала могут создавать только ключи с режимом «только чтение». Попытка выпустить ключ с режимом READWRITE отклоняется с кодом 403 KEY_POLICY_READONLY_REQUIRED. Администратор портала не подпадает под это ограничение и при необходимости создаёт ключи с записью или меняет режим чужого ключа в его карточке.

Существующие ключи политика портала не затрагивает — она применяется только в момент создания нового ключа. Для уже выпущенных ключей администратор меняет режим вручную в карточке ключа.

#Пример ответа при блокировке записи

POST /v1/leads с ключом в режиме READONLY возвращает 403:

{
  "success": false,
  "error": {
    "code": "WRITE_BLOCKED_READONLY_KEY",
    "message": "Key is in read-only mode. Switch to read+write in /keys to enable writes.",
    "details": {
      "method": "crm.item.add",
      "keyName": "MCP key",
      "currentMode": "READONLY",
      "switchUrl": "/keys"
    }
  }
}

Поле details.method присутствует только в ответе на блокировку при проксировании в Битрикс24 — оно содержит имя метода, который был бы вызван при успешной записи. Для менеджмент-ключей details.method не возвращается: в блокировке участвует только HTTP-метод запроса.

Подробное описание кода ошибки, причины срабатывания и шаги для разблокировки — `WRITE_BLOCKED_READONLY_KEY`.

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

• Скоупы
• Быстрый старт
• Менеджмент-ключи
• Коды ошибок