Для AI-агентов: markdown этой страницы — /docs-content/keys-auth.md индекс документации — /llms.txt
Создание и использование ключа
Ключ — это учётные данные для доступа к API Вайбкод. Эта страница проводит через создание ключа в личном кабинете шаг за шагом и разбирает каждый параметр формы: название, скоупы, срок действия, лимит запросов и список разрешённых IP.
Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key
Скоуп — это разрешение на доступ к определённой группе данных портала. Какие скоупы выбрать под задачу — на отдельной странице Скоупы.
Разделы документации
- Самоописание ключа — что
GET /v1/meрассказывает о ключе, портале, тарифе и доступных возможностях - Авторизация пользователей приложения — вход через Битрикс24 и обмен на токен сессии для приложений от лица разных пользователей
- Справочник API для модели —
GET /v1/guide, контракт полей всех сущностей без токена сессии - Режим доступа — ключ только на чтение, политика портала, блокировка записи
Типы ключей
| Тип | Префикс | Назначение | Авторизация |
|---|---|---|---|
| ТипAPI-ключ | Префиксvibe_api_ |
НазначениеДоступ к данным портала через API Вайбкод | АвторизацияЗаголовок X-Api-Key |
| ТипКлюч авторизации | Префиксvibe_app_ |
НазначениеВстраивание приложения в портал и OAuth-авторизация Битрикс24 | АвторизацияX-Api-Key + токен сессии |
| ТипМенеджмент-ключ | Префиксvibe_live_ |
НазначениеАдминистрирование платформы | АвторизацияЗаголовок X-Api-Key |
API-ключ (vibe_api_). Создаётся в личном кабинете и привязан к одному порталу Битрикс24. Все запросы идут от лица владельца ключа, токен сессии не требуется. Подходит для личных сводных панелей, скриптов, серверных интеграций и ботов на своём портале.
Ключ авторизации (vibe_app_). Привязан к Вайбкод-приложению с OAuth-учётными данными Битрикс24. Каждый запрос отправляется от лица пользователя, установившего приложение и прошедшего авторизацию, — поэтому нужен заголовок Authorization: Bearer. Подходит для приложений из каталога, которые работают от лица разных пользователей того портала, где приложение зарегистрировано. Этот же ключ нужен, чтобы приложение открывалось внутри Битрикс24 — в левом меню, вкладке CRM или виджете (раздел Встраивание приложения в портал).
Менеджмент-ключ (vibe_live_). Не привязан к одному порталу, предназначен для администрирования: управления ключами, просмотра порталов, работы с обратной связью. Доступа к данным сущностей Битрикс24 не имеет. Полное описание — Менеджмент-ключи.
Дальше — создание обоих ключей портала: API-ключа (vibe_api_) и ключа авторизации (vibe_app_). Формы отличаются, отличие описано ниже. Менеджмент-ключ (vibe_live_) описан отдельно — Менеджмент-ключи.
Создание API-ключа
- Войдите в личный кабинет.
- Откройте раздел Ключи API.
- Нажмите Создать.
- Заполните форму (шаги ниже).
- Скопируйте ключ — он показывается один раз.
Шаг 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_) — перевыпустите ключ авторизации на карточке приложения, передав полный нужный набор скоупов вscopes(POST /api/applications/:id/reissue-auth-key), и пройдите авторизацию заново. Карточка приложения, его данные и сервер сохраняются; удалять и создавать приложение заново не нужно.
Скоуп выдаётся при выпуске только если он доступен на портале Битрикс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-ключа: всего два поля.
- Откройте раздел Ключи авторизации и нажмите Создать.
- Название — под ним приложение видно в списке.
- Скоупы — те же две группы «Битрикс24» и «Вайбкод», минимум один. Подбор набора описан на странице Скоупы.
- Скопируйте ключ — он показывается один раз.
Срок действия, лимит запросов и список разрешённых IP в этой форме не задаются — этим она и отличается от формы API-ключа. После создания ключ авторизации работает в паре с токеном сессии: каждый запрос отправляется с заголовками X-Api-Key и Authorization: Bearer (раздел «Передача ключа»).
Код для AI-агента: первая выдача и перевыпуск
При первой выдаче ключа авторизации на карточке приложения окно может предложить одноразовый код вместо секрета. Скопируйте промпт из окна агенту: он начнёт с GET /v1/me и получит рецепт безопасного сохранения единственной переменной VIBE_APP_KEY. Это отдельный код получения ключа, а не код входа пользователя через OAuth.
При первой выдаче агент не заменяет существующее присваивание VIBE_APP_KEY в .env: он останавливается до получения секрета. При перевыпуске сначала проверяет, что локальное значение соответствует именно заменённому ключу, даже если тот уже отозван. Другой ключ, в том числе того же владельца, заменять нельзя. Если новый ключ уже записан, повторное действие не требуется. Не обходите отказ рецепта: в окне остаётся действие «Показать ключ» для ручной установки.
Код и промпт исчезают после закрытия окна. Повторное открытие читает ту же доставку; новый код для неё получается только отдельным действием. Истечение срока или отмена кода не отзывает уже созданный ключ и не повторяет выдачу. Если ответ потерян, сначала дождитесь проверки текущей карточки и доставки нового ключа, не запускайте перевыпуск повторно. При неизвестном результате обновления окружения проверьте VIBE_APP_KEY на сервере вручную. После перевыпуска по-прежнему нужно завершить авторизацию; затем окно восстановит прежние размещения.
Код перевыпуска получает только владелец приложения. Администратор, действующий за другого владельца, не получает ни секрет, ни доставку. Если запись доставки не удалась, владелец один раз получает обычный секрет уже выпущенного ключа: повторного перевыпуска нет.
Для сессионных запросов кабинета код включается только одновременно доступной функцией и заголовком x-vibe-key-delivery: code: POST /api/applications/:id/auth-key возвращает delivery с меткой auth_first, а POST /api/applications/:id/reissue-auth-key — auth_reissue. В обоих случаях доставка содержит одну часть auth для VIBE_APP_KEY; вместо rawSecret приходит delivery. Без заголовка или при недоступной функции сохраняется прежний ответ. Встройка, которая не показывает ключ, заголовок не отправляет. Эти сессионные ручки не относятся к публичному OpenAPI /v1.
Встраивание приложения в портал
Если приложение должно открываться внутри Битрикс24 — пунктом в левом меню, вкладкой в карточке CRM или виджетом на рабочем столе, — для этого нужен ключ авторизации (vibe_app_). API-ключ (vibe_api_) встраивание в интерфейс портала не поддерживает: с ним приложение обращается к данным, но не размещается в окне Битрикс24.
Ключ авторизации даёт две возможности, которых нет у API-ключа:
- Размещение в интерфейсе. Приложение появляется в выбранном месте портала — за это отвечает привязка места встраивания. Доступные места возвращает справочник, полный порядок работы — Места встраивания.
- Прозрачная авторизация. Пользователь открывает приложение внутри Битрикс24 без отдельного входа: Gateway сам определяет, кто открыл приложение, и передаёт его данные серверу приложения. Браузер токен сессии не видит.
Порядок действий:
- Создайте ключ авторизации в разделе Ключи авторизации — форма описана выше в разделе «Создание ключа авторизации».
- Передайте AI-модели именно ключ авторизации (
vibe_app_) и попросите приложение со встраиванием в портал. - Модель вызовет
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 для такого вызова сам подсказывает оба пути.
Что каким способом читать:
| Что нужно | Чем авторизоваться | Куда идти |
|---|---|---|
Что нужноСтатический контракт полей (типы, readonly, enum, required, createOnly) — до установки, без сессии |
Чем авторизоватьсяключ авторизации по X-Api-Key (без Bearer) |
Куда идтиGET /v1/guide → поле data.entities[].fieldsDetailed |
Что нужноНазвания полей для отображения, живые поля портала и пользовательские поля UF_CRM_* |
Чем авторизоватьсясессия (Bearer) на ключе авторизации или персональный API-ключ (vibe_api_…) |
Куда идтиGET /v1/<entity>/fields, GET /v1/userfields/* |
Токен сессии живёт 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) требует, чтобы платформа точно знала, кто создаёт сервер — это нужно для тарифной проверки и учёта в лимитах. Для ключей 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 входят и ключи авторизации приложений, и ключи, выписанные самой платформой, поэтому число бывает больше, чем список ключей в кабинете: там показаны не все из них. Расхождение ожидаемое, а не потеря записей.
Жизненный цикл ключа
Создание → Активен → Перевыпуск / Отзыв / Удаление
Состояния ключа
| Состояние | Значение в API | Описание |
|---|---|---|
| СостояниеАктивен | Значение в APIACTIVE |
ОписаниеКлюч готов к использованию |
| СостояниеИстёк | Значение в APIACTIVE |
ОписаниеДата в поле expiresAt прошла. Поле status при этом остаётся ACTIVE — истечение определяется по дате, а запросы отклоняются с кодом 401 KEY_EXPIRED |
| СостояниеОтозван | Значение в APIREVOKED |
ОписаниеКлюч деактивирован, запросы отклоняются |
Готовность к вызовам Битрикс24
status: ACTIVE означает, что платформа принимает ключ, — но не то, что вызовы к
порталу выполнимы. Личный ключ (vibe_api_) ходит в Битрикс24 по вебхуку, и вебхука
на ключе может не быть: например, у портала нет активной подписки на Битрикс24 Маркет
в момент выдачи ключа. Такой ключ проходит авторизацию, работает с эндпоинтами самой
платформы Вайбкод — и отвечает 401 TOKEN_MISSING на любой вызов к порталу.
Готовность видна двумя способами:
| Где | Что смотреть |
|---|---|
ГдеGET /v1/keys и GET /v1/keys/{id} |
Что смотретьпризнак b24Ready: true — вебхук есть, false — нет, null — к ключу не применимо (ключ приложения, управляющий ключ или ключ без скоупов Битрикс24) |
ГдеGET /v1/me |
Что смотретьблок b24Credentials у личного ключа: ready, а при ready: false — reason, paywallCode, upgradeUrl и подсказка hint |
Причины и действия по каждой из них — Коды ошибок. Общий порядок: устранить причину на портале, затем переподключить ключ — в кабинете на странице «API-ключи», пункт «Переподключить» в меню ключа. Ключ получает вебхук, а сама строка ключа не меняется. Новый ключ нужен только там, где переподключение не применимо: ключи приложения, системные ключи и ключи без скоупов Битрикс24.
Ответ /v1/me кэшируется на 30 секунд, поэтому сразу после починки читайте его как
GET /v1/me?refresh=tariff.
Перевыпуск
Перевыпуск создаёт новый API-ключ. Старый активный ключ может работать не дольше 24 часов после перевыпуска и не дольше своего прежнего срока действия (expiresAt). Перевыпуск не продлевает этот срок и не восстанавливает истёкший ключ. Для заблокированного ключа (BLOCKED) отсрочки нет.
- Запустите перевыпуск в личном кабинете.
- Получите новый ключ.
- Обновите ключ в своих приложениях.
- Старый активный ключ работает до более ранней границы: 24 часа после перевыпуска или прежний срок действия. Для заблокированного ключа отсрочки нет.
- По истечении переходного периода старый ключ становится недействительным.
Ключ авторизации приложения
Переходный период выше относится к API-ключам. Перевыпуск ключа авторизации приложения создаёт новую OAuth-регистрацию. Старый ключ отзывается после привязки нового.
При перевыпуске ключа авторизации на карточке приложения новый ключ принадлежит владельцу карточки, даже если перевыпуск запустил администратор. Действие администратора фиксируется в аудите. Новый секрет показывается один раз только владельцу приложения. При перевыпуске администратором за другого владельца секрет в ответ не попадает: платформа пробует заменить его в окружении приложения, а ответ сообщает результат доставки. Если сервера нет или доставка не удалась, владельцу нужно самостоятельно перевыпустить ключ для ручной установки. Квота проверяется у владельца: замена его собственного ключа не требует свободного места, а замена старого ключа другого пользователя требует. Персональный доступ к 1С проверяется у нового владельца ключа. Права другого человека не переносятся автоматически.
Если владелец неактивен на портале, перевыпуск отклоняется с APPLICATION_AUTH_KEY_OWNER_INACTIVE. Сначала передайте приложение активному сотруднику через действие «Передать», затем перевыпустите ключ. Администратор может передать приложение себе. При передаче принадлежащие прежнему владельцу неотозванные ключи приложения сразу переходят новому владельцу, но секрет ключа авторизации остаётся прежним до перевыпуска. Поэтому после передачи перевыпустите его: прежние копии будут отозваны. Само обновление платформы не мигрирует ранее выданные ключи.
Отзыв и удаление
Чтобы отозвать API-ключ, откройте «API-ключи» в личном кабинете, найдите нужный активный ключ и в меню ⋮ его строки выберите «Деактивировать». После сохранения отзыва ключ получает состояние REVOKED («Отозван»).
После сохранения отзыва кэш ключа сбрасывается на обработавшем запрос сервере, а другие серверы получают уведомление. При потере этого уведомления другой сервер может ещё принимать ключ до истечения закэшированного состояния. Текущий срок жизни этого кэша (TTL) — около 5 минут. После обновления состояния на этом сервере запросы с отозванным ключом отклоняются с 401 KEY_INACTIVE.
«Удалить» в том же меню — отдельное действие удаления ключа. Для отзыва достаточно «Деактивировать». Перевыпуск создаёт новый API-ключ. Старый активный ключ может работать до 24 часов после перевыпуска, но не дольше своего прежнего срока действия. Для заблокированного ключа (BLOCKED) отсрочки нет. Для отзыва старого активного ключа выберите «Деактивировать» и учитывайте описанную выше задержку распространения отзыва.
Если на ключе есть активные серверы, удаление возвращает 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 — им управляют не здесь, а в разделе «Подключённые приложения» вашего профиля. Отзыв там гасит сразу все ключи, которые вы выдали этому приложению для этого портала. Отзыв одной строки в списке ключей погасит только её.
Если владельца ключа отметили уволенным
Когда проверка сотрудников портала находит, что владелец ключа уволен в Битрикс24, его ключи на этом портале отвечают 403 OWNER_BLOCKED. Ключ при этом не отзывается и остаётся в состоянии ACTIVE: как только Битрикс24 снова показывает сотрудника активным, ключ работает без перевыпуска. Отказ касается всех ключей этого человека на портале — личных, ключей его OAuth-приложений и ключей, на которых работают его приложения, агенты и боты, — у всех пользователей портала.
- Интеграции нужен ключ от имени активного сотрудника портала — выпустите его и замените старый.
- Администратор портала передаёт приложения, серверы, агентов и ботов уволенного другому сотруднику в карточке сотрудника в разделе «Пользователи».
- Если отметка ошибочна, исправьте статус сотрудника в Битрикс24 — после следующей проверки ключ снова заработает. Если после восстановления сотрудника в Битрикс24 ключ так и не заработал, обратитесь в поддержку.
Если ключ скомпрометирован
- Откройте «API-ключи», найдите скомпрометированный ключ и в меню ⋮ его строки выберите «Деактивировать». После сохранения отзыва ключ получает статус
REVOKED. При потере уведомления об отзыве другой сервер может ещё принимать ключ до истечения закэшированного состояния (текущий TTL — около 5 минут). После обновления состояния на этом сервере запросы отклоняются с401 KEY_INACTIVE. - Создайте новый ключ с теми же скоупами.
- Обновите ключ во всех приложениях.
- Если на отозванном ключе были серверы, смените у них управляющий ключ на новый — Восстановление доступа к серверу.
- Проверьте журнал запросов на обращения с неизвестных адресов.
- Включите список разрешённых IP.
Рекомендации по безопасности
- Храните ключи в переменных окружения или менеджере секретов, не в коде и не в git.
- Не передавайте ключи через мессенджеры и почту.
- Назначайте ключу только необходимые скоупы — подбор набора описан на странице Скоупы.
- Заводите отдельный ключ для каждого сервиса и отзывайте неиспользуемые.
- Для серверных интеграций включайте список разрешённых IP и конечный срок действия.
- Перевыпускайте ключи по расписанию (например, раз в 90 дней).
Лимиты запросов
Скорость вызовов ограничивают три независимых механизма: граница платформы Вайбкод, лимит портала Битрикс24 и собственные лимиты отдельных эндпоинтов. Отдельно от них считается дневная квота на вызовы API — она описана ниже.
Граница платформы Вайбкод
Основное ограничение для /v1/. Считается по IP-адресу клиента и общее для всех ключей, вызывающих с этого адреса. У части эндпоинтов на границе действует свой, более строгий лимит — тогда применяется он.
| Параметр | Значение |
|---|---|
| ПараметрЛимит | Значение60 запросов в секунду на IP-адрес клиента |
| ПараметрЗапас на всплеск | Значение100 запросов сверх лимита |
| ПараметрОтвет при превышении | Значение429 с кодом RATE_LIMITED |
| ПараметрЗаголовок паузы | ЗначениеRetry-After: 1 |
Отказ формируется на границе платформы, до входа в приложение, поэтому заголовков 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 операциями расходует одну единицу.
Собственные лимиты эндпоинтов
Часть эндпоинтов несёт вдобавок поминутный лимит на ключ — он строже границы платформы и защищает тяжёлые или необратимые операции. Действующее значение и остаток приходят в заголовках ответа:
| Заголовок | Значение |
|---|---|
ЗаголовокX-RateLimit-Limit |
Значениелимит окна |
ЗаголовокX-RateLimit-Remaining |
Значениеостаток в текущем окне |
ЗаголовокX-RateLimit-Reset |
Значениесекунды до сброса окна |
Если этих заголовков в ответе нет, собственного лимита у эндпоинта нет — действует только граница платформы.
AI-эндпоинты (/v1/chat/completions, /v1/models, /v1/audio/transcriptions) считают два ведра: на ключ и на пользователя. Их отказ несёт Retry-After и заголовок X-RateLimit-Scope, который называет исчерпанное ведро.
Дневная квота на вызовы API
Когда на аккаунте Битрикс24 подключена оплата вызовов API с бесплатной дневной нормой, ответы несут три заголовка:
| Заголовок | Значение |
|---|---|
ЗаголовокX-RateLimit-Quota |
Значениедневная норма |
ЗаголовокX-RateLimit-Used |
Значениеизрасходовано за сегодня |
ЗаголовокX-RateLimit-Remaining |
Значениеостаток нормы |
X-RateLimit-Used и X-RateLimit-Remaining считают расход по закрытым часам: вызовы текущего часа попадают в счёт после его окончания. Поэтому заголовки отстают от фактического расхода до 70 минут. Если остаток нужен точно, ведите на своей стороне счёт вызовов, которые заголовки ещё не учли.
Это отдельный механизм от лимитов скорости выше, и 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-*, следите за остатком и снижайте темп заранее.
Справочник эндпоинтов
| Метод | Путь | Описание |
|---|---|---|
| МетодGET | Путь/v1/me |
ОписаниеСамоописание ключа: тип, портал, скоупы, лимиты, доступные возможности |
| МетодGET | Путь/v1/guide |
ОписаниеКонтракт полей всех сущностей и правила работы с API |
| МетодGET | Путь/v1/oauth/authorize |
ОписаниеНачать авторизацию пользователя приложения — перенаправление на страницу входа Битрикс24 |
| МетодGET | Путь/v1/oauth/callback |
ОписаниеПриём ответа Битрикс24. Вызывается Битрикс24, не приложением |
| МетодPOST | Путь/v1/oauth/token |
ОписаниеОбменять код на токен сессии |
| МетодGET | Путь/v1/oauth/poll |
ОписаниеЗабрать результат авторизации без своего redirect_uri |
| МетодPOST | Путь/v1/oauth/placement-session |
ОписаниеТокен сессии для приложения на своём сервере |
| МетодPOST | Путь/v1/oauth/revoke |
ОписаниеОтозвать токен сессии |
Коды ошибок
| HTTP | Код | Когда возвращается |
|---|---|---|
| HTTP401 | КодKEY_INACTIVE |
Когда возвращаетсяКлюч отозван или заблокирован платформой |
| HTTP401 | КодKEY_EXPIRED |
Когда возвращаетсяУ ключа задан срок действия, и он прошёл |
| HTTP401 | КодINVALID_API_KEY |
Когда возвращаетсяКлюч не опознан: такой строки на платформе нет |
| HTTP401 | КодTOKEN_MISSING |
Когда возвращаетсяУ ключа нет учётных данных Битрикс24: для vibe_app_ не передан Authorization: Bearer, для vibe_api_ — на ключе нет вебхука портала (причина в error.details, см. Коды ошибок) |
| HTTP401 | КодWRONG_AUTH_SCHEME |
Когда возвращаетсяКлюч авторизации vibe_app_ передан в заголовке Authorization: Bearer. Ключ приложения передаётся в X-Api-Key, а Authorization: Bearer несёт сессионный токен. Клиенту, который умеет только Bearer, подходит личный ключ vibe_api_ |
| HTTP403 | КодIP_NOT_ALLOWED |
Когда возвращаетсяЗапрос с адреса вне списка разрешённых IP |
| HTTP403 | КодOWNER_BLOCKED |
Когда возвращаетсяВладелец ключа заблокирован или больше не активен на портале — подробнее |
| HTTP403 | КодWRITE_BLOCKED_READONLY_KEY |
Когда возвращаетсяУ ключа задан режим «только чтение», а вызов выполняет запись — Режим доступа |
Полный справочник кодов — Коды ошибок.