Для 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-приложение
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-приложение
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, а не по наличию права в списке.
Пример ответа
{
"api_key": "vibe_api_...",
"portal": {
"domain": "example.bitrix24.ru",
"name": "Моя компания"
},
"scopes": ["crm", "task"],
"granted_scopes": ["crm", "task"],
"user": {
"name": "Иван Иванов",
"email": "ivan@example.com"
}
}
Пример ответа при ошибке
400 — не передан обязательный параметр:
{
"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 — Ошибки.