Для AI-агентов: markdown этой страницы — /docs-content/partner-connect/token.md индекс документации — /llms.txt

Обменять код на API-ключ

POST /v1/connect/token

Обменивает одноразовый код авторизации на постоянный API-ключ. Принимает application/json и application/x-www-form-urlencoded.

Поля запроса (body)

Поле Тип Обяз. Описание
Полеgrant_type Типstring Обяз.да ОписаниеДля этого потока — authorization_code. Без него эндпоинт отвечает unsupported_grant_type. Другой режим того же эндпоинта — urn:ietf:params:oauth:grant-type:device_code (см. Вход с устройства без браузера).
Полеclient_id Типstring Обяз.да ОписаниеИдентификатор партнёра
Полеclient_secret Типstring Обяз.условно ОписаниеСекрет партнёра. Обязателен для конфиденциального клиента, передавать только с серверной стороны. Публичный клиент (PUBLIC) его не передаёт
Полеcode Типstring Обяз.да ОписаниеКод из параметра code редиректа
Полеredirect_uri Типstring Обяз.да ОписаниеТот же redirect_uri, что был передан в /v1/connect/authorize
Полеcode_verifier Типstring Обяз.условно ОписаниеИсходная строка PKCE. Обязательна, если при авторизации передан code_challenge, в том числе для клиента с секретом

Примеры

Эндпоинт авторизуется учётными данными приложения — client_id и client_secret в теле запроса. Заголовки X-Api-Key и Authorization не нужны.

curl — OAuth-приложение

Terminal
curl -X POST https://vibecode.bitrix24.tech/v1/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=RECEIVED_CODE \
  -d redirect_uri=https://yourapp.com/callback

JavaScript — OAuth-приложение

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    code: receivedCode,
    redirect_uri: 'https://yourapp.com/callback',
  }),
})

const data = await res.json()
// data.api_key — постоянный API-ключ Вайбкод
// data.portal — выбранный пользователем портал
// data.scopes — запрошенные скоупы, data.granted_scopes — права ключа
// data.user — пользователь, выдавший доступ

Поля ответа

Поле Тип Описание
Полеapi_key Типstring ОписаниеAPI-ключ Вайбкод в формате vibe_api_.... Передавать в заголовке X-Api-Key при последующих вызовах
Полеportal.domain Типstring ОписаниеДомен портала Битрикс24, например example.bitrix24.ru
Полеportal.name Типstring ОписаниеНазвание портала
Полеscopes Типstring[] ОписаниеПрава, запрошенные приложением. На странице согласия пользователь подтверждает набор целиком
Полеgranted_scopes Типstring[] ОписаниеПрава, которые реально несёт выданный ключ. У самостоятельно зарегистрированного партнёрского приложения как правило, совпадают со scopes. Разойдутся, если права ключа изменили после согласия
Полеuser.name Типstring ОписаниеИмя пользователя, выдавшего доступ
Полеuser.email Типstring ОписаниеЭлектронная почта пользователя

Два набора прав расходятся только у приложений, которым состав прав назначает сама платформа — например у настольного приложения Коворк/Код. Такое приложение может не запрашивать ничего, тогда scopes приходит пустым, а granted_scopes перечисляет весь набор ключа. Проверяйте доступ по granted_scopes.

Поле granted_scopes может отсутствовать в ответе, если платформа не смогла прочитать права выданного ключа. Пустым оно при этом не приходит, поэтому отсутствие поля означает «набор неизвестен», а не «прав нет» — в таком ответе ориентируйтесь на scopes.

Набор в granted_scopes отражает то, что записано в ключе. Отдельное право портал Битрикс24 может не подтвердить на своей стороне, поэтому отказ разбирайте по коду ответа Битрикс24, а не по наличию права в списке.

Пример ответа

JSON
{
  "api_key": "vibe_api_...",
  "portal": {
    "domain": "example.bitrix24.ru",
    "name": "Моя компания"
  },
  "scopes": ["crm", "task"],
  "granted_scopes": ["crm", "task"],
  "user": {
    "name": "Иван Иванов",
    "email": "ivan@example.com"
  }
}

Пример ответа при ошибке

400 — не передан обязательный параметр:

JSON
{
  "error": "invalid_request",
  "error_description": "Missing client_id, code or redirect_uri"
}

Ошибки

Эндпоинт отвечает в форме RFC 6749 — { error, error_description }, без обёртки success. Это сделано ради совместимости с готовыми OAuth-библиотеками. Исключение — отказ ограничителя частоты самого эндпоинта, его форма описана после таблицы.

HTTP error Условие
HTTP400 errorinvalid_request УсловиеНе передан один из client_id, code, redirect_uri
HTTP400 errorinvalid_grant УсловиеКод не существует, истёк, уже был использован, либо redirect_uri не совпадает с переданным в /v1/connect/authorize
HTTP400 errorinvalid_grant УсловиеПроверка PKCE не прошла: code_verifier не передан либо не соответствует переданному ранее code_challenge. Код при этом уже израсходован: повтор с верным code_verifier тоже вернёт invalid_grant, авторизацию начинают заново
HTTP400 errorinvalid_client УсловиеПубличный клиент прислал client_secret — публичному клиенту секрет не выдаётся и передавать его нельзя
HTTP400 errorunsupported_grant_type Условиеgrant_type не передан или не входит в режимы, перечисленные в поле grant_type выше
HTTP401 errorinvalid_client Условиеclient_id неизвестен, клиент отключён, либо client_secret не совпадает
HTTP403 erroraccess_denied УсловиеКлиент в режиме COMPANY, и в выдаче ключа Компании отказано. code и error_description несут машинный код причины: CONNECT_COMPANY_NOT_READY — технические условия подключения не выполнены, CONNECT_COMPANY_DISABLED — подключение недоступно для этого пользователя или портала. Подробнее — Подключение Компании
HTTP400 errorinvalid_request УсловиеОпрос входа с устройства: не передан client_id или device_code. error_description — Missing client_id or device_code
HTTP401 errorinvalid_client УсловиеОпрос входа с устройства: клиент неизвестен, отключён или вход с устройства ему не разрешён
HTTP400 errorunauthorized_client УсловиеОпрос входа с устройства от клиента в режиме COMPANY. code и error_description — CONNECT_COMPANY_DEVICE_FLOW_FORBIDDEN
HTTP429 errorslow_down УсловиеПревышен лимит частоты на входе в платформу. Лимит считается по адресу вызывающего и общий для обмена кода и опроса устройства. Ответ несёт Retry-After с минимальной паузой в секундах и не несёт заголовков X-RateLimit-*

Ограничителей частоты два, и оба отвечают 429. Различать их по заголовку X-RateLimit-Limit. Отказ на входе в платформу из таблицы выше этого заголовка не несёт и приходит в форме RFC 6749. Отказ самого эндпоинта его несёт, а тело приходит в общем конверте API — { "success": false, "error": { "code": "RATE_LIMITED", "message": "..." } }. Действие в обоих случаях одно: подождать и повторить, увеличив паузу.

Отказы выдачи, переподключения и ротации секрета в режиме COMPANY приходят с HTTP 400, 403, 409, 429 и 503 и полем code, отказ 429 CONNECT_COMPANY_ATTEMPT_LIMITED несёт ещё retryAfterSeconds — перечень в разделе Переподключение и ротация секрета.

Полный справочник общих ошибок API — Ошибки.

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