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

Ключ — это учётные данные для доступа к 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. Предвыбор действует только для ключей, которые вы создаёте себе: ключу стороннего приложения из Partner Connect права не добавляются, он несёт ровно подтверждённые пользователем.

Набор скоупов Битрикс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. Лимит запросов

Необязательный поминутный лимит на обращения ключа к AI-эндпоинтам. Пустое поле означает общий лимит платформы для AI-вызовов.

Задать значение может только администратор портала. Остальным поле в форме недоступно, а попытка передать его через API отклоняется с кодом 403 RATE_LIMIT_ADMIN_ONLY.

На остальные эндпоинты /v1/ поле не влияет — их скорость ограничивают граница платформы и лимит портала, см. раздел «Лимиты запросов».

Шаг 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 отвечает с сессией и без неё — Самоописание ключа.

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

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

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

Есть и второй предел — портальный потолок платформы. Он считается по всем живым ключам портала, а не по одному сотруднику. Его значение задаёт платформа, поэтому администратор портала не поднимает такой потолок настройкой «Макс. ключей на пользователя».

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

Состояние квоты приходит вместе с отказом, в error.details: limit — сколько ключей разрешено, used — сколько занято, а requested, если оно есть, — сколько новых ключей нужно операции. Если поля scope нет, сработал лимит пользователя на портале: его можно поднять в настройках портала, если limit меньше 100, либо освободить место отзывом ненужных ключей. Если пришло scope: "portal", сработал портальный потолок платформы: удаление отдельных ключей помогает только когда общее число живых ключей портала становится ниже limit. В 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 самых новых. Смените у них управляющий ключ — Восстановление доступа к серверу. Удалять сами серверы для этого не нужно. Если ключом управляется агент, управляемый бот или обычный чат-бот (включая отключённую строку Bot Platform), удаление возвращает 409 KEY_HAS_LINKED_AGENT: число агентов — в поле details.linkedAgentCount, число ботов — в details.linkedBotCount (управляемые + обычные чат-боты), а details.bots содержит до 10 блокирующих обычных чат-ботов с внутренним botId и числовым bitrixBotId. Возьмите bitrixBotId именно из ответа 409 и сначала удалите чат-бота через DELETE /v1/bots/:botId или перенесите его на другой ключ.

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

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

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

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

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

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

Скорость вызовов ограничивают три независимых механизма: граница платформы Вайбкод, лимит портала Битрикс24 и собственные лимиты отдельных эндпоинтов. Отдельно от них считается дневная квота на вызовы API — она описана ниже.

Граница платформы Вайбкод

Основное ограничение для /v1/. Считается по IP-адресу клиента и общее для всех ключей, вызывающих с этого адреса. У части эндпоинтов на границе действует свой, более строгий лимит — тогда применяется он.

Отказ формируется на границе платформы, до входа в приложение, поэтому заголовков X-RateLimit-* в нём нет. Ориентир для повтора — Retry-After.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 1 second."
  }
}

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

Битрикс24 ограничивает скорость обращений на уровне портала, и все ключи портала делят этот лимит. Когда одиночный вызов целиком отклонён с QUERY_LIMIT_EXCEEDED, Вайбкод возвращает 429 RATE_LIMITED с заголовком Retry-After: 2. При автопагинации общий ответ может остаться 200, а тот же код приходит в meta.pageErrorSample; в POST /v1/batch проверяйте ошибки подвызовов. Поле rateLimit.requestsPerSecond в GET /v1/me содержит справочное значение лимита Битрикс24 — 10 запросов в секунду; это не индивидуальная настройка и не измеренное действующее значение для конкретного ключа.

Один вызов считается за единицу. Один POST /v1/batch с 50 операциями расходует одну единицу.

Собственные лимиты эндпоинтов

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

Если этих заголовков в ответе нет, собственного лимита у эндпоинта нет — действует только граница платформы.

AI-эндпоинты (/v1/chat/completions, /v1/models, /v1/audio/transcriptions) считают два ведра: на ключ и на пользователя. Их отказ несёт Retry-After и заголовок X-RateLimit-Scope, который называет исчерпанное ведро.

Дневная квота на вызовы API

Когда на аккаунте Битрикс24 подключена оплата вызовов API с бесплатной дневной нормой, ответы несут три заголовка:

Это отдельный механизм от лимитов скорости выше, и X-RateLimit-Remaining здесь означает остаток дневной нормы, а не остаток окна. Отличить механизмы можно по соседним заголовкам: X-RateLimit-Quota и X-RateLimit-Used приходят только с дневной квотой, X-RateLimit-Limit и X-RateLimit-Reset — только с лимитом окна.

Отсутствие этих трёх заголовков означает, что счётчика вызовов на аккаунте нет. Это не ошибка и не признак сбоя.

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

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

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

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

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

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

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