#Ключи и авторизация

Vibe API использует ключи доступа для аутентификации запросов. Каждый ключ имеет тип, набор скоупов и настройки безопасности.

#Типы ключей

#API-ключи (`vibe_api_`)

Основной тип для работы с данными. Создается в личном кабинете, работает сразу после создания.

• Доступ к сущностям Битрикс24 через единые эндпоинты
• Настраиваемые скоупы для ограничения доступа
• Ограничение вызовов по списку разрешённых IP
• Индивидуальные лимиты запросов

#Ключи авторизации (`vibe_app_`)

Привязаны к Вайбкод-приложению с OAuth-учётными данными Битрикс24 (Client ID и Client Secret).

• Работают через OAuth 2.0 Битрикс24
• Автоматическое продление токенов
• Скоупы определяются настройками приложения
• Подходят для интеграций, которые устанавливаются на портал

#Менеджмент-ключи (`vibe_live_`)

Не привязаны к одному порталу и предназначены для администрирования: управления API-ключами, просмотра списка порталов, работы с обратной связью. Не имеют доступа к данным сущностей Битрикс24.

Полное описание возможностей, скоупов и эндпоинтов — на странице Менеджмент-ключи.

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

Основной заголовок для всех типов ключей — X-Api-Key:

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

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

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

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

Для iframe-встраивания через Bitrix24 placement (POST /v1/bitrix-handler с PLACEMENT) токен vibe_session_* передаётся иначе: backend возвращает HTML auto-submit форму и отправляет токен в теле POST в поле access_token (а не в query string URL приложения).

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

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

Эндпоинт GET /v1/me возвращает полную информацию о ключе: тип, скоупы, портал, доступные сущности и эндпоинты.

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

Ответ зависит от типа ключа.

#API-ключ (`vibe_api_`)

{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.ru",
    "scopes": ["crm", "task", "user"],
    "api": {
      "_rules": ["ALWAYS use entity API for ANY entity listed below", "..."],
      "entityApi": {
        "entities": { "deals": "/v1/deals", "contacts": "/v1/contacts", "tasks": "/v1/tasks" },
        "operations": ["GET (list/by-id)", "POST (create)", "PATCH (update)", "DELETE", "POST /search"]
      },
      "botApi": { "endpoints": { "register": "POST /v1/bots", "events": "GET /v1/bots/:botId/events" } },
      "batch": { "endpoint": "POST /v1/batch" }
    },
    "rateLimit": { "requestsPerSecond": 10 },
    "errorCodes": { "format": "{ success: false, error: { code, message } }", "codes": { "400": {}, "401": {}, "429": {}, "502": {} } },
    "deployment": { "available": true, "quickstart": ["1. POST /v1/infra/servers", "2. GET /v1/infra/servers/:id", "3. POST /v1/infra/servers/:id/deploy"] },
    "auth": { "header": "X-Api-Key: <this-key>" },
    "owner": { "name": "Иван Петров" },
    "expiresAt": null
  }
}

Секция api содержит все доступные эндпоинты: Entity API, Bot API, Chat API, Telephony, Workflows и др. Секция ai появляется при наличии скоупа vibe:ai.

#Ключ авторизации (`vibe_app_`)

{
  "success": true,
  "data": {
    "type": "oauth_app",
    "portal": "mycompany.bitrix24.ru",
    "scopes": ["crm", "task"],
    "api": { "...": "..." },
    "auth": {
      "header": "X-Api-Key: <this-key> + Authorization: Bearer <session-token>",
      "steps": ["1. Redirect user to authorizeUrl", "2. Exchange code for session", "3. Call API with both headers"]
    },
    "app": { "title": "CRM Dashboard", "id": "12" },
    "oauth": {
      "authorizeUrl": "https://vibecode.bitrix24.tech/v1/oauth/authorize?app_key=...",
      "tokenUrl": "https://vibecode.bitrix24.tech/v1/oauth/token"
    },
    "oauthTutorial": { "steps": ["...4 шага с примерами запросов и ответов..."] },
    "placements": { "available": ["CRM_DEAL_DETAIL_TAB", "..."], "registered": [] }
  }
}

Содержит OAuth-флоу с пошаговым туториалом, доступные виджеты и информацию о приложении.

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

Эндпоинт /v1/me — основная точка входа для AI-моделей. При работе с Вайбкод через Claude Code, Cursor или ChatGPT достаточно дать модели ключ и ссылку https://vibecode.bitrix24.tech/v1/me — модель сама разберётся в структуре API.

#Скоупы

Скоупы определяют, к каким данным Битрикс24 имеет доступ ключ, а также к каким разделам платформы Вайбкод (vibe:*). При создании ключа выберите только необходимые скоупы.

#Скоупы Битрикс24

#Скоупы платформы Вайбкод

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

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

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

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

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

Пример заголовков:

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

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

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

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

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

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

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

Для повышения безопасности можно ограничить вызовы ключа списком IP-адресов.

#Настройка

1. Перейдите в настройки ключа в личном кабинете
2. Включите ограничение по IP
3. Добавьте список разрешённых IP-адресов

#Формат

Поддерживаются только точные IP-адреса (IPv4 и IPv6). CIDR-подсети не поддерживаются — каждый адрес указывается отдельной строкой.

192.168.1.100
203.0.113.42
2001:db8::1

Запросы с IP-адресов, не входящих в список, отклоняются с кодом 403 IP_NOT_ALLOWED.

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

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

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

Связанные коды ошибок при работе с неактивным ключом:

#Перевыпуск ключа

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

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

Перевыпуск доступен для ключей авторизации (vibe_app_).

#Отзыв ключа

Перевод ключа в состояние REVOKED. Все последующие запросы с этим ключом отклоняются с ответом 401 Unauthorized и кодом KEY_INACTIVE. Если на ключе остались активные серверы, удаление возвращает 409 KEY_HAS_ACTIVE_SERVERS — серверы нужно удалить первыми.

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

#Хранение ключей

• Храните ключи в переменных окружения, не в коде
• Используйте менеджеры секретов (Vault, AWS Secrets Manager и аналоги)
• Не сохраняйте ключи в git-репозиторий
• Не передавайте ключи через мессенджеры или почту

#Минимальные привилегии

• Создавайте отдельные ключи для разных сервисов
• Назначайте только необходимые скоупы
• Включайте список разрешённых IP для серверных интеграций
• Регулярно проверяйте и отзывайте неиспользуемые ключи

#Мониторинг

• Отслеживайте необычную активность по ключам
• Настройте уведомления о превышении лимитов
• Проверяйте журнал запросов на обращения с неизвестных IP-адресов
• Регулярно перевыпускайте ключи (раз в 90 дней)

#Реагирование на компрометацию

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

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

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

• Менеджмент-ключи — отдельная страница про vibe_live_ ключи и администрирование платформы
• Быстрый старт — первый запрос за 2 минуты
• Оптимизация и batch — ускорение в 50 раз через POST /v1/batch, паттерны, известные ограничения
• CLI и cURL — примеры работы через командную строку
• MCP для AI — интеграция с AI-инструментами
• Подключение Битрикс24 к OpenClaw — npm-плагин для самостоятельно развёрнутого OpenClaw
• Коды ошибок — справочник ошибок API