Авторизация, ключи и права

Подробный разбор кодов, которыми API Вайбкод отвечает, когда ключ не опознан, ему не хватает прав или он работает в режиме «только чтение».

Сводная таблица всех кодов API Вайбкод — Коды ошибок.

`MISSING_API_KEY` (401)

Запрос не содержит заголовка X-Api-Key.

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Причины:

• Не передан заголовок X-Api-Key или Authorization.
• Заголовок передан с пустым значением.

Решение:

• Добавить заголовок X-Api-Key: vibe_api_... или X-Api-Key: vibe_app_....
• Проверить, что переменная окружения с ключом установлена корректно (для CLI-утилит и SDK).

`INVALID_API_KEY` (401)

Платформа не нашла такой строки ключа: переданное значение не совпадает ни с одним выданным ключом.

Этот код не означает, что ваш ключ перестал действовать. Ключ, который существует, но не проходит, отвечает другими кодами: отозванный или заблокированный — KEY_INACTIVE, с истёкшим сроком — KEY_EXPIRED, с отклонёнными порталом учётными данными — PORTAL_CREDENTIALS_REJECTED. Порядок действий у этих состояний разный, поэтому начинайте с кода в ответе. Сводка кодов — Ошибки, состояния ключа и их признаки — Ключи и авторизация.

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Причины:

• Опечатка или лишние пробелы в ключе.
• Значение обрезано при копировании или переносе в переменную окружения.
• Ключ от другого окружения — тестового вместо боевого или наоборот.
• Ключ удалён владельцем или администратором.
• Префикс не из числа поддерживаемых: vibe_api_, vibe_app_, vibe_live_.

Решение — по порядку:

1. Сверить саму строку, которую отправляет клиент: лишние пробелы и переносы, обрезанное значение, ключ от другого окружения. Искажённую при передаче строку перевыпуск не лечит.
2. Найти ключ на странице его вида: личный (vibe_api_) — Ключи API, ключ авторизации приложения (vibe_app_) — карточка приложения в разделе Приложения, а если карточки там нет — в разделе Ключи авторизации, менеджмент-ключ (vibe_live_) — Менеджмент-ключи. Раздел «Ключи API» показывает только личные ключи, поэтому отсутствие там ключа приложения или менеджмент-ключа не означает, что он удалён.
3. Создать новый ключ — только если ключ действительно удалён. Ключ, который нашёлся на своей странице и отправляется без искажений, этим кодом не отвечает, и новый ключ ничего не изменит.

`TOKEN_MISSING` (401)

У ключа нет кредов Битрикс24, поэтому вызов к порталу выполнить нечем. Причина зависит от типа ключа, и это два разных сценария.

Личный ключ (vibe_api_*) ходит в портал по вебхуку. Если вебхука на ключе нет, ответ на вызовах сущностей (/v1/{сущность} и POST /v1/batch) несёт машиночитаемую причину в error.details. На остальных маршрутах приходит тот же код без details:

{
  "success": false,
  "error": {
    "code": "TOKEN_MISSING",
    "message": "This personal API key (vibe_api_*) has no Bitrix24 webhook credentials, ...",
    "details": {
      "reason": "B24_MARKET_SUBSCRIPTION_REQUIRED",
      "paywallCode": "B24_MARKET_SUBSCRIPTION_REQUIRED"
    }
  }
}

Значения details.reason:

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

Важно: переподключение доступно НЕ каждому ключу: платформа отбивает его ответом 400 RECONNECT_NOT_APPLICABLE для ключей приложений, ключей со служебным назначением (в том числе ключа Коворка), ключей, привязанных к серверу, к живому агенту или к живому управляемому боту, и ключей без скоупов Битрикс24. Таким ключам текст ошибки переподключение и не предлагает: там нужно закрыть причину на портале. Вебхук после этого платформа выпускает сама только ключу Коворка.

paywallCode приходит только для тарифных причин. Вместе с ним может прийти upgradeUrl — ссылка на страницу подключения на портале. У INT_TARIFF_REQUIRED её нет.

Те же три условия закрывают установку приложения и привязку места встраивания — там они приходят самостоятельными кодами 403, разбор — Биллинг, тариф и подписка.

Ключ приложения (vibe_app_*) держит токены портала в пользовательской сессии, а не на ключе. Вызов только с X-Api-Key, без Authorization: Bearer <токен сессии>, законно отвечает TOKEN_MISSING — details в этой ветке не приходит, а message описывает пропущенный шаг OAuth. Полный поток — Ключи и авторизация.

Как посмотреть состояние ключа заранее: GET /v1/me для личного ключа отдаёт блок b24Credentials (ready, а при ready: false — та же reason и действия), а GET /v1/keys — признак b24Ready на каждом ключе. Ответ /v1/me кэшируется на 30 секунд, поэтому сразу после починки на портале читайте его как GET /v1/me?refresh=tariff — иначе до полуминуты будет отдаваться прежнее состояние. У GET /v1/keys кэша нет.

`TOKEN_REFRESH_FAILED` (401)

Авторизация портала для этого ключа не обновилась. Поле error.scope равно "apiKey"; целевой метод не был отправлен в Битрикс24. Восстановите авторизацию ключа перед повтором — один backoff причину не устранит.

`PORTAL_CREDENTIALS_REJECTED` (401)

Битрикс24 отклонил учётные данные, с которыми платформа обращается к порталу от имени ключа. Отличие от TOKEN_MISSING: там учётных данных у ключа нет вовсе, здесь они есть, но портал их больше не принимает — вебхук отозван, удалён на портале или потерял силу вместе с правами владельца.

{
  "success": false,
  "error": {
    "code": "PORTAL_CREDENTIALS_REJECTED",
    "message": "Bitrix24 rejected the credentials this key calls the portal with",
    "hint": "The portal no longer accepts the webhook or token behind this key. Reconnect the key to the portal (or re-issue it) — Retrying will not help until the credentials are restored.",
    "scope": "apiKey"
  }
}

Повтор запроса не помогает: пока креды не восстановлены, портал отклоняет каждый вызов этого ключа одинаково. Код приходит на любом маршруте, который читает данные портала, и в подошибке POST /v1/batch.

Что делать: переподключить ключ на странице «API-ключи» либо, если переподключение к ключу не применимо, создать новый. Ограничения переподключения те же, что у TOKEN_MISSING выше.

Как отличить от отказа по правам: нехватка прав приходит кодами SCOPE_DENIED (403) и BITRIX_ACCESS_DENIED (403) — там креды приняты, но операция закрыта. PORTAL_CREDENTIALS_REJECTED означает, что портал не признал сами креды, и никакая настройка прав этого не изменит.

`PORTAL_ADDRESS_CHANGED` (409)

Коробочный портал переехал на новый адрес, а вебхук ключа остался выписан на прежний. Платформа не отправляет секрет туда, где портала больше нет, поэтому вызов отклоняется до обращения к порталу. Отличие от PORTAL_CREDENTIALS_REJECTED: там учётные данные отклонил сам портал, здесь запрос до портала не доходит — адрес, на который выписан вебхук, больше не адрес портала.

{
  "success": false,
  "error": {
    "code": "PORTAL_ADDRESS_CHANGED",
    "message": "Portal address changed: this credential is issued for the portal's previous address. Re-issue the key webhook to continue",
    "scope": "apiKey"
  }
}

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

Тем же кодом отвечает и правка прав такого ключа — PATCH /v1/keys/:id с новым списком scopes. Запрос к порталу не отправляется, права ключа не меняются ни на платформе Вайбкод, ни в Битрикс24.

Что делать: переподключить ключ на странице «API-ключи». Платформа перевыпустит вебхук на текущий адрес портала, строка ключа и его права не изменятся, интеграции перенастраивать не нужно. Отклонённую правку прав повторите после переподключения. Ограничения переподключения те же, что у TOKEN_MISSING выше.

`SCOPE_DENIED` (403)

У ключа нет нужного скоупа для запрошенной операции.

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope",
    "hint": "This request needs the 'crm' scope, which the calling key does not carry. Add 'crm' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "crm",
    "keyScopes": ["calendar", "vibe:ai", "vibe:search"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "Ключу приложения не хватает права «CRM». Добавить его можно в настройках ключа в кабинете разработчика."
  }
}

Причины:

• Для CRM-сущностей нужен скоуп crm, для задач — task, для бот-платформы — imbot, для AI Router — vibe:ai, для инфраструктуры — vibe:infra.
• Справочник сотрудников GET /v1/users и остальные методы этого раздела открывает только полное право user. Сокращённые права user_basic и user_brief его не заменяют — перечень и границы прав на странице Скоупы.
• Скоуп ключа сужен на этапе создания.

Поля отказа. Отказ по скоупу самого ключа несёт error.cause = key_scope_missing, недостающий скоуп в error.requiredScope, скоупы ключа в этом запросе в error.keyScopes, действие в error.fix, пояснение на английском в error.hint и текст для человека в error.userMessage. Так отвечают генерируемые маршруты сущностей (включая их пакетные и агрегатные вызовы и include), заметки, закрепление и привязки записей таймлайна, открытые линии и маршруты активностей, адресов, бронирований, ботов, календаря, звонков, обзвонов, складских документов и изображений товаров каталога, чатов, платежей, доставок, документов, форм, поиска, карточек, справочников и трассировок CRM, файлов и папок диска, шаблонов документов, оргструктуры, списков, почты, заметок, уведомлений, 1С, публикации страниц, ленты, реквизитов, пользовательских полей, веб-поиска, скрама, задач, пользователей, складов, рабочего дня, бизнес-процессов, рабочих групп, журнала таймлайна, регулярных сделок и CRM-триггеров, а с теми же полями приходят INSUFFICIENT_SCOPE маршрутов /v1/cowork/*, INFRA_SCOPE_REQUIRED и SCOPE_NOT_ALLOWED пакетного запроса. Если маршруту нужны два скоупа, error.requiredScope называет первый недостающий. Код, статус и error.message прежние. error.keyScopes включает выданные автоматически vibe:ai и vibe:search, поэтому бывает шире data.scopes из GET /v1/me.

Для части ключей, созданных в кабинете, ответ может не знать, выдан ли ключ через Partner Connect. Генерируемые маршруты сущностей (включая их пакетные и агрегатные вызовы и include), маршруты остальных областей из абзаца «Поля отказа», пакетный запрос и INFRA_SCOPE_REQUIRED это определяют и отвечают по строкам таблицы. Заметки, закрепление и привязки записей таймлайна и открытые линии — нет: такому ключу там приходит fix.action = none, а error.hint и error.userMessage говорят, что определить это не удалось. Для ключа, который платформа выпустила под конкретную задачу, ответ тоже говорит «не определено»: подействует ли на него правка набора прав, не известно. При fix.action = none текст error.userMessage различает три случая: право этому ключу не добавить; определить это не удалось; ключ выдан через Partner Connect — тогда право добавляет разработчик приложения, заново запросив согласие пользователя.

error.userMessage можно показать человеку как есть: в нём название права из настроек ключа и то, где его добавить, без ссылок и разметки. В пакетном запросе элементы data.errors с кодом SCOPE_NOT_ALLOWED несут cause, requiredScope, fix и hint, а keyScopes и userMessage приходят один раз — в самом ответе 403, когда по скоупу отклонены все вызовы. Если вызовам нужны разные скоупы, requiredScope в ответе нет. Вызов, отклонённый кодом OAUTH_REQUIRED, этих полей не получает; ответ, в котором он есть, — тоже.

Решение:

• Действовать по error.fix, если ответ его несёт: таблица выше.
• Полный список скоупов и их назначение — на странице Ключи и авторизация.

Ключ, выданный через Partner Connect, — отдельный случай. Его набор задаёт не форма ключа, а страница согласия, поэтому перевыпуск ничего не добавит: право надо запросить и получить подтверждение пользователя заново. Со стороны приложения — отметить нужное право в карточке приложения и провести пользователя через согласие ещё раз. Новый ключ придёт уже с ним. vibe:ai приложение отмечает само, vibe:storage приложению Connect не выдаётся, остальные платформенные права выдаёт платформенный администратор — порядок в разделе Платформенные права. Такой ключ видно по имени в списке ключей: Connect: <название приложения>.

`BITRIX_ACCESS_DENIED` (403)

Битрикс24 отказал в доступе к методу или сущности. Отказ бывает двух видов, и снимаются они по-разному: у пользователя Битрикс24, от имени которого идёт вызов, нет прав — или учётным данным ключа не хватает скоупа. Вид отказа приходит в error.cause, действие — в error.fix, пояснение на английском — в error.hint. Метод Битрикс24, который отказал, приходит в error.method, имя длиннее 100 символов обрезается.

{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "Access denied",
    "hint": "Bitrix24 reports an access-rights refusal for crm.item.fields, not a scope error. The Bitrix24 user this call runs as lacks access; ask a portal admin to grant it, or call under a user who has it. For this method Bitrix24 requires read permission for items of this CRM entity type (entityTypeId).",
    "cause": "b24_permission",
    "method": "crm.item.fields",
    "fix": { "action": "grant_b24_rights", "via": "portal_admin" }
  }
}

Причины — поле cause. Набор открытый: незнакомое значение читайте как unknown.

Действие — поле fix. action — что сделать, via — где. Набор action открытый: незнакомое значение читайте как none.

«cabinet, portal_admin и platform — шаг человека: передай его пользователю и не повторяй вызов, пока он не сделан». same_key и management_api агент выполняет сам, если у него есть нужный ключ. Набор via тоже открытый: незнакомое значение читайте как шаг человека.

Когда fix.action — none при cause: b24_scope. Действия нет, если его совет был бы ложным:

• Ключ выпущен платформой под конкретную задачу — Cowork/Code, обслуживание сервера, доступ соавтора — или привязан к серверу. Неизвестно, подействует ли на такой ключ добавление скоупа, — hint так и говорит.
• Ключ с зафиксированным набором прав. Такой ключ создают в кабинете или выдают через Partner Connect, и при этом отказе платформа их не различает. Поэтому неизвестно, что добавит скоуп: правка ключа или повторное согласие, которое приложение запрашивает у пользователя, — hint так и говорит.
• Скоуп placement, entity или userfieldtype личному вебхуку Битрикс24 не выдаёт — для такого метода нужен ключ авторизации приложения.
• Скоуп у ключа есть, а вебхук на портале отстал. Платформа могла уже починить вебхук сама — повторите вызов один раз. Если отказ повторяется, пользователь переподключает ключ командой «Переподключить» в разделе Ключи API. Для ключей, привязанных к агенту или управляемому боту, она недоступна.
• Скоуп метода неизвестен — сверьте скоуп метода в документации REST Битрикс24 с data.scopes из GET /v1/me.
• Ключ OAuth-приложения, которое видно только в разделе «Ключи авторизации» кабинета, а не в «Приложениях» — например, созданного через API или на странице «Ключи авторизации». Машинного действия для такого ключа нет: человек выпускает новый ключ авторизации в разделе «Ключи авторизации» (Перевыпустить ключ) с нужными скоупами или создаёт новое приложение сразу с нужным набором.
• Ключ ходит в Битрикс24 по легаси OAuth-токенам, выданным самому ключу. Перевыпуск ключа авторизации приложения к нему не относится. Нужен новый ключ API или OAuth-приложение с этим скоупом — это шаг человека.

Коды ACCESS_DENIED_EXTEND и NO_AUTH_FOUND приходят не как 403, а как 422 BITRIX_ERROR с b24Code, и такими остаются. В ответе на них те же cause, method, fix и hint.

Тот же отказ Битрикс24 отдаёт, когда запрашиваемый модуль выключен на портале (нет CRM, бот-платформы и тому подобного). Если права пользователя и скоупы ключа в порядке, проверьте это.

Как скоупы закрепляются за ключом, как перевыпустить ключ и что делать, если после перевыпуска отказ повторяется, — Ключи и авторизация.

`BOT_ACCESS_DENIED` (403)

Бот привязан к другому ключу API. Операции с ботом выполняются ключом, к которому он привязан, а вызов любым другим ключом получает отказ. error.cause — bot_other_key, пояснение на английском — в error.hint.

{
  "success": false,
  "error": {
    "code": "BOT_ACCESS_DENIED",
    "message": "This bot belongs to a different API key",
    "hint": "This bot is bound to another API key on this Bitrix24 account, and bot operations run only with the key the bot is bound to. To move the bot to this key, call POST /v1/bots/42/transfer with this key and error.fix.body as the request body. After the transfer, check the bot's access with POST /v1/bots/42/reauth.",
    "cause": "bot_other_key",
    "fix": {
      "action": "transfer_bot",
      "via": "same_key",
      "path": "POST /v1/bots/42/transfer",
      "body": { "targetApiKeyId": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33" }
    }
  }
}

fix.action — transfer_bot, когда вызывающий ключ может сам перенести бота на себя. Для этого ключу должна быть открыта запись на платформе и он должен годиться во владельцы бота. Его пользователь Вайбкод должен владеть текущим ключом бота или быть администратором портала Битрикс24, а бот не должен управляться агентом или управляемым ботом. Вызовите fix.path тем же ключом с телом fix.body. fix.body.targetApiKeyId — идентификатор самого вызывающего ключа. Ключ, к которому привязан бот, в ответе не называется. После переноса проверьте привязку — Восстановление доступа к боту.

fix.action — none: машинного действия нет, используйте ключ, к которому привязан бот. Так бывает, когда:

• вызывающий ключ не может выполнить перенос сам: у него режим «только чтение», а перенос — запись на платформе;
• вызывающий ключ не может владеть ботом: это служебный ключ платформы, у него нет скоупа imbot, он истёк или не активен;
• перенести бота на этот ключ может только тот же пользователь Вайбкод, который владеет текущим ключом бота, или администратор портала Битрикс24, а вызывающий не из их числа;
• ботом управляет агент или управляемый бот — ключ меняется через этот ресурс;
• проверку не удалось выполнить для этого запроса.

Какой это случай, называет hint.

`WRITE_BLOCKED_READONLY_KEY` (403)

У ключа задан режим «только чтение» (accessMode: "READONLY"), а запрос выполняет запись. Полное описание режима, переключения и политики портала — Режим доступа.

{
  "success": false,
  "error": {
    "code": "WRITE_BLOCKED_READONLY_KEY",
    "message": "Key is in read-only mode. Switch the key to read and write in /keys to allow Bitrix24 data changes.",
    "details": {
      "method": "crm.item.add",
      "keyName": "MCP key",
      "currentMode": "READONLY",
      "switchUrl": "/keys"
    }
  }
}

Важно: switchUrl — не константа. В примере выше личный ключ, поэтому путь ведёт на страницу ключей. Раздел «Ключи API» по построению показывает ТОЛЬКО личные ключи, поэтому у остальных видов путь другой: у менеджмент-ключа (vibe_live_*) — /management-keys, а у ключа авторизации приложения (vibe_app_*) — одна из ДВУХ страниц: «Приложения» /applications, если у приложения есть карточка в этом разделе, иначе «Ключи авторизации» /apps. Читайте значение из ответа, а не подставляйте своё.

Поля details:

Причины:

• API-ключ или ключ авторизации (vibe_api_, vibe_app_) в режиме READONLY выполнил вызов, который проксируется в Битрикс24 как операция записи: создание, обновление, удаление, действие над сущностью.
• Менеджмент-ключ (vibe_live_) в режиме READONLY выполнил запрос с HTTP-методом POST, PATCH, PUT или DELETE — например, попытка создать ключ через POST /v1/keys или удалить запись обратной связи.

Решение:

• Владельцу личного ключа (vibe_api_) — открыть Ключи API, в карточке нужного ключа в блоке Режим доступа выбрать «Чтение и запись» и сохранить. Режим применяется к следующему запросу, перевыпуск не нужен.
• Владельцу менеджмент-ключа (vibe_live_) — открыть Менеджмент-ключи и переключить режим в карточке ключа. В разделе «Ключи API» такой ключ не показывается по построению, поэтому шаг выше для него неприменим.
• Владельцу ключа авторизации приложения (vibe_app_) — переключить режим в карточке приложения, в блоке Режим доступа. В разделе «Ключи API» такой ключ не показывается по построению, поэтому шаг выше для него неприменим. Карточка живёт на одной из двух страниц: Приложения, если приложение заведено в этом разделе, иначе Ключи авторизации — там карточка открывается из меню строки, пункт «Информация». Не гадайте: адрес нужной страницы всегда приходит в details.switchUrl — идите по нему, а не по фиксированному пути.
• Если в карточке выбор переключателя недоступен — администратор портала ограничил режим. Запросить у администратора снятие ограничения для этого ключа.
• При работе через AI-агента — действующий режим возвращает GET /v1/me в поле data.accessMode. Если запись нужна постоянно, выпустить отдельный ключ с режимом «чтение и запись».

`OWNER_BLOCKED` (403)

Владелец ключа заблокирован или больше не активен на портале.

{
  "success": false,
  "error": {
    "code": "OWNER_BLOCKED",
    "message": "Key owner is blocked"
  }
}

Причины:

• Платформа заблокировала аккаунт владельца ключа.
• Владелец ключа удалён из Битрикс24 или его учётная запись передана другому человеку.
• Проверка сотрудников портала отметила владельца ключа уволенным в Битрикс24. Доступ приостановлен отметкой об увольнении — обратитесь к администратору портала.

Решение:

• Сотруднику, чей ключ отклонён, — обратиться к администратору портала.
• Интеграции — перейти на ключ активного сотрудника портала. Ключ уволенного не отзывается и снова заработает, когда Битрикс24 покажет сотрудника активным — Если владельца ключа отметили уволенным. Если после восстановления сотрудника в Битрикс24 ключ так и не заработал, обратитесь в поддержку.

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

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