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

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

Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

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

Разделы документации

• Самоописание ключа — что GET /v1/me рассказывает о ключе, портале, тарифе и доступных возможностях
• Авторизация пользователей приложения — вход через Битрикс24 и обмен на токен сессии для приложений от лица разных пользователей
• Справочник API для модели — GET /v1/guide, контракт полей всех сущностей без токена сессии
• Режим доступа — ключ только на чтение, политика портала, блокировка записи

Типы ключей

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, vibe:feedback) отмечены в форме заранее — ключ, выпущенный без правок, получает их все. Галочки при этом рабочие: снимите ненужные, и ключ выпустится ровно с оставшимися. Ключ только с vibe:storage вернёт 403 на создание сервера и на вызовы AI.

Набор скоупов Битрикс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-ключа:

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

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

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

Полный жизненный цикл встроенного приложения, паттерн BFF — отдельный сервер-посредник для фронтенда и примеры обработчика на Node, Python и Go — Авторизация в приложении на BlackHole.

Приложение на своём сервере

Если приложение размещено на собственном сервере, а не за BlackHole, и открывается как размещение, страница согласия Битрикс24 внутри iframe не открывается. Токен сессии текущего пользователя получают через одноразовый код или POST /v1/oauth/placement-session — по тому, чей обработчик принимает размещение. Порядок для обоих случаев — Авторизация пользователей приложения.

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

Ключ передаётся в заголовке 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. Способ с одним заголовком Authorization: Bearer применим только к ключам vibe_api_ и vibe_live_.

Для ключа авторизации (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/guide и /v1/oauth/* работают без Bearer.

Это касается и эндпоинтов схемы — GET /v1/<entity>/fields и GET /v1/userfields/*: они выглядят как статическая схема, но запрашивают метаданные полей (включая пользовательские) у Битрикс24 в реальном времени, поэтому тоже требуют пользовательского контекста. Для сценария «узнать доступные поля до встраивания приложения и появления сессии пользователя» используйте персональный API-ключ (vibe_api_…) — он отдаёт схему по одному заголовку X-Api-Key, без Bearer. Ответ 401 TOKEN_MISSING для такого вызова сам подсказывает оба пути.

Что каким способом читать:

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

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

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

Как GET /v1/me отвечает с сессией и без неё — Самоописание ключа.

Сколько ключей можно создать

Число ключей на одного пользователя портала ограничено. По умолчанию — 10 ключей. Значение задаёт администратор аккаунта в кабинете, на странице «Настройки» → карточка «Лимиты для пользователей» → поле «Макс. ключей на пользователя», и может поднять его до 100.

В этот лимит входят все ключи пользователя на портале — и API-ключи (vibe_api_), и ключи авторизации (vibe_app_), которые создаются при регистрации приложений. Отдельного лимита на приложения нет. Приложения расходуют тот же счётчик, что и личные ключи.

Когда лимит достигнут, создание нового ключа или приложения возвращает 409 KEY_LIMIT_REACHED. В счёт лимита идут ключи в любом состоянии, кроме отозванного, поэтому истёкший ключ место не освобождает — чтобы освободить место, отзовите неиспользуемый ключ.

Состояние квоты приходит вместе с отказом, в error.details: limit — сколько ключей разрешено, used — сколько занято. В used входят и ключи авторизации приложений, и ключи, выписанные самой платформой, поэтому число бывает больше, чем список ключей в кабинете: там показаны не все из них. Расхождение ожидаемое, а не потеря записей.

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

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

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

Готовность к вызовам Битрикс24

status: ACTIVE означает, что платформа принимает ключ, — но не то, что вызовы к порталу выполнимы. Личный ключ (vibe_api_) ходит в Битрикс24 по вебхуку, и вебхука на ключе может не быть: например, у портала нет активной подписки на Битрикс24 Маркет в момент выдачи ключа. Такой ключ проходит авторизацию, работает с эндпоинтами самой платформы Вайбкод — и отвечает 401 TOKEN_MISSING на любой вызов к порталу.

Готовность видна двумя способами:

Причины и действия по каждой из них — Коды ошибок. Общий порядок: устранить причину на портале, затем переподключить ключ — POST /api/keys/:id/reconnect выдаёт вебхук существующему ключу, не меняя саму строку ключа. Новый ключ нужен только там, где переподключение не применимо: ключи приложения, системные ключи и ключи без скоупов Битрикс24.

Ответ /v1/me кэшируется на 30 секунд, поэтому сразу после починки читайте его как GET /v1/me?refresh=tariff.

Перевыпуск

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

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

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

Отзыв переводит ключ в состояние REVOKED: последующие запросы отклоняются с 401 KEY_INACTIVE. Если на ключе есть активные серверы, удаление возвращает 409 KEY_HAS_ACTIVE_SERVERS: полное число серверов — в поле details.activeServerCount, а в details.servers приходит список не больше чем из 10 самых новых. Смените у них управляющий ключ — Восстановление доступа к серверу. Удалять сами серверы для этого не нужно. Если ключом управляется агент или бот, удаление возвращает 409 KEY_HAS_LINKED_AGENT: число агентов — в поле details.linkedAgentCount, число ботов — в details.linkedBotCount, а в details.agents приходит список не больше чем из 10 связанных агентов. Сначала удалите агента или бота.

Ключ с именем Connect: <приложение> выдан стороннему приложению через Partner Connect — им управляют не здесь, а в разделе «Подключённые приложения» вашего профиля. Отзыв там гасит сразу все ключи, которые вы выдали этому приложению для этого портала; отзыв одной строки в списке ключей погасит только её.

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

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

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

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

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

К каждому ключу одновременно применяются две независимые системы лимитов: лимит платформы Вайбкод и лимит портала Битрикс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-*, чтобы не доводить до отказа.

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

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

Справочник эндпоинтов

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

• Самоописание ключа
• Авторизация пользователей приложения
• Справочник API для модели
• Режим доступа
• Восстановление доступа к серверу
• Подключение коробочного Битрикс24
• Скоупы
• Менеджмент-ключи
• Коды ошибок