Partner Connect

Подключение внешних сервисов к Битрикс24: ваше приложение запрашивает у пользователя разрешение на доступ к его порталу и получает API-ключ Вайбкод для дальнейших вызовов. Поток построен по схеме Authorization Code — той же, что у OAuth-провайдеров Google или GitHub.

Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: client_id + client_secret партнёра | Скоупы ключа: запрашиваются на странице согласия

Содержание

• Когда применять
• Как это работает
• Справочник эндпоинтов
• Полный сценарий — Express-обработчик от и до
• GET /v1/connect/authorize — старт потока, редирект на согласие
• POST /v1/connect/token — обмен кода на API-ключ
• Публичный клиент: поток с PKCE — приложение без сервера
• Вход с устройства без браузера — телевизор, приставка, терминал
• Использование API-ключа
• Доступные скоупы
• Время жизни и отзыв ключа
• Безопасность
• Регистрация партнёра
• Типы клиента — публичный или конфиденциальный, с примерами
• Смотрите также

Когда применять

Сценарий — внешний SaaS-продукт, который интегрируется с порталами Битрикс24 ваших клиентов: CRM-аналитика, синхронизация с 1С, чат-ассистент, конструктор лендингов. Кнопка «Подключить Битрикс24» на вашем сайте запускает поток: пользователь выбирает портал и подтверждает скоупы, ваш сервер получает постоянный API-ключ и работает с порталом от имени пользователя.

Если вы пишете приложение, которое ставится внутри портала Битрикс24 и работает только с ним, — используйте обычный API-ключ, см. Ключи и авторизация.

Как это работает

Ваше приложение → [1. Redirect] → Вайбкод Consent Page → [2. Согласие]
    ↑                                                          ↓
    └──── [4. API-ключ] ←── [3. Code → redirect_uri] ──────────┘

1. Redirect — отправляете пользователя на /v1/connect/authorize с client_id, redirect_uri, state и списком скоупов.
2. Согласие — пользователь видит страницу Вайбкод, выбирает портал и подтверждает или отклоняет запрошенные скоупы.
3. Код — после одобрения пользователь возвращается на redirect_uri с параметрами code и state. При отказе — redirect_uri?error=access_denied&state=....
4. Обмен — сервер партнёра отправляет POST /v1/connect/token и получает API-ключ.

Справочник эндпоинтов

Полный сценарий

Пример Express-обработчика, который проводит пользователя через оба эндпоинта от и до. Перед запуском поместите client_id и client_secret, полученные при регистрации клиента, в переменные окружения, а redirect_uri зарегистрируйте у этого клиента.

import express from 'express'
import crypto from 'node:crypto'

const app = express()
const sessions = new Map() // в продакшене — Redis или БД

const CLIENT_ID = process.env.PARTNER_CLIENT_ID
const CLIENT_SECRET = process.env.PARTNER_CLIENT_SECRET
const REDIRECT_URI = 'https://yourapp.com/callback'

// 1. Кнопка «Подключить Битрикс24» ведёт сюда
app.get('/connect', (req, res) => {
  const state = crypto.randomBytes(16).toString('hex')
  sessions.set(state, { userId: req.user.id, createdAt: Date.now() })

  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'crm task',
    state,
  })
  res.redirect(`https://vibecode.bitrix24.tech/v1/connect/authorize?${params}`)
})

// 2. Вайбкод возвращает пользователя сюда после согласия или отказа
app.get('/callback', async (req, res) => {
  const { code, state, error } = req.query

  const session = sessions.get(state)
  if (!session) return res.status(400).send('Неизвестный state')
  sessions.delete(state)

  if (error === 'access_denied') {
    return res.redirect('/dashboard?connect=denied')
  }

  // 3. Обмениваем код на API-ключ — серверный запрос с client_secret
  const tokenRes = 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: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code,
      redirect_uri: REDIRECT_URI,
    }),
  })
  const data = await tokenRes.json()

  if (!tokenRes.ok) {
    // Ошибка приходит в RFC-форме: { error, error_description }
    return res.status(400).send(`Ошибка обмена: ${data.error}`)
  }

  // 4. Сохраняем привязку: пользователь нашего сервиса ↔ портал Битрикс24
  await db.connections.upsert({
    userId: session.userId,
    portalDomain: data.portal.domain,
    portalName: data.portal.name,
    apiKey: encrypt(data.api_key), // секрет, шифруем перед хранением
    scopes: data.scopes,
  })

  res.redirect('/dashboard?connect=ok')
})

// 5. Дальше используем сохранённый ключ для вызовов от имени пользователя
async function listDeals(userId) {
  const connection = await db.connections.findByUserId(userId)
  const apiKey = decrypt(connection.apiKey)

  const res = await fetch('https://vibecode.bitrix24.tech/v1/deals?limit=10', {
    headers: { 'X-Api-Key': apiKey },
  })
  return res.json()
}

Ключевые моменты сценария:

• state генерируется на сервере и проверяется при возврате — без этой проверки злоумышленник может подсунуть пользователю чужой код.
• client_secret хранится только на сервере и в браузер не попадает.
• API-ключ шифруется перед записью в БД и расшифровывается только в момент вызова.
• При error=access_denied пользователь видит понятное сообщение, а не страницу с ошибкой обмена.

GET /v1/connect/authorize

Перенаправляет пользователя на страницу согласия Битрикс24 Вайбкод.

Query-параметры:

Пример URL:

https://vibecode.bitrix24.tech/v1/connect/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&scope=crm%20task&state=abc123random

Успешный редирект после одобрения:

https://yourapp.com/callback?code=AUTH_CODE_HERE&state=abc123random

Редирект при отказе пользователя на странице согласия:

https://yourapp.com/callback?error=access_denied&state=abc123random

Ошибки

Ошибки этого эндпоинта приходят двумя разными путями, и обработать нужно оба.

До того как redirect_uri проверен — обычный ответ 400 с телом RFC 6749. Возвращать пользователя некуда: адрес ещё не подтверждён, редирект на непроверенный URL был бы дырой.

{
  "error": "invalid_client",
  "error_description": "Unknown or inactive client"
}

После того как redirect_uri проверен — редирект обратно на него с параметрами error и state (RFC 6749 §4.1.2.1). Ваш обработчик redirect_uri обязан это разбирать.

https://yourapp.com/callback?error=invalid_scope&state=abc123random

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

POST /v1/connect/token

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

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

Примеры

curl

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

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 — пользователь, выдавший доступ

Поля ответа

Два набора прав расходятся только у приложений, которым состав прав назначает сама платформа — например у настольного приложения Cowork. Такое приложение может не запрашивать ничего, тогда 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-библиотеками.

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

Публичный клиент: поток с PKCE

Всё выше описывает конфиденциальный клиент — тот, у которого есть сервер и client_secret. Если сервера нет и секрет спрятать негде (мобильное приложение, десктопная программа, одностраничное веб-приложение), регистрируйте публичный клиент. Секрет ему не выдаётся, подлинность подтверждается механизмом PKCE.

Отличий от основного потока три, всё остальное совпадает.

1. Приложение генерирует пару на каждый запуск потока. Случайная строка (code_verifier) и её SHA-256-хеш в base64url без выравнивающих знаков = (code_challenge).

import crypto from 'node:crypto'

const b64url = (buf) => buf.toString('base64url')
const verifier  = b64url(crypto.randomBytes(32))
const challenge = b64url(crypto.createHash('sha256').update(verifier).digest())

verifier держите до конца потока, challenge уходит в первый запрос.

2. В /v1/connect/authorize добавляются два параметра.

Для публичного клиента они обязательны: без них поток завершится редиректом ?error=invalid_request.

3. В /v1/connect/token вместо client_secret уходит code_verifier.

curl -X POST https://vibecode.bitrix24.tech/v1/connect/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "code": "RECEIVED_CODE",
    "redirect_uri": "http://127.0.0.1:9999/callback",
    "code_verifier": "CODE_VERIFIER"
  }'

Ответ тот же, что у конфиденциального клиента:

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

client_secret публичному клиенту передавать нельзя — платформа ответит 400 invalid_client. Это не придирка: секрет, зашитый в раздаваемое приложение, секретом не является, и поток построен так, чтобы им нельзя было пользоваться.

Возврат на localhost

У программы без своего сайта нет публичного адреса, куда вернуть код. Для таких случаев разрешён возврат на себя: зарегистрируйте redirect_uri вида http://127.0.0.1:9999/callback, поднимите на время потока временный слушатель на этом порту и закройте его сразу после получения кода.

Порт при сверке не учитывается — если занят, приложение может слушать любой другой, повторно регистрировать адрес не нужно. Годятся 127.0.0.1, localhost и [::1], схема http для них разрешена. Все остальные адреса обязаны быть https.

Вход с устройства без браузера

Телевизор, приставка, утилита в терминале — там, где неудобно вводить логин и пароль. Пользователь подтверждает вход на телефоне или компьютере, а доступ получает устройство. Поток описан стандартом RFC 8628.

Устройству нужен разрешённый device-режим: он включается платформенным администратором и только проверенным приложениям. Клиент, зарегистрированный самостоятельно, получит 400 unauthorized_client — это защита пользователей от того, чтобы код подтверждения показывало непроверенное приложение.

Шаг 1. Устройство запрашивает код.

curl -X POST https://vibecode.bitrix24.tech/v1/connect/device/authorize \
  -H "Content-Type: application/json" \
  -d '{"client_id":"YOUR_CLIENT_ID","scope":"crm","code_challenge":"ХЕШ","code_challenge_method":"S256"}'

{
  "device_code": "MYQnuWB3H0tR...",
  "user_code": "54BV-XT8F",
  "verification_uri": "https://vibecode.bitrix24.tech/connect/device",
  "verification_uri_complete": "https://vibecode.bitrix24.tech/connect/device?user_code=54BV-XT8F",
  "expires_in": 899,
  "interval": 5
}

device_code — секрет устройства, на экран не выводится. user_code показывается пользователю вместе с адресом. expires_in — сколько секунд у пользователя есть на подтверждение.

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

Шаг 3. Устройство опрашивает /v1/connect/token.

curl -X POST https://vibecode.bitrix24.tech/v1/connect/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "client_id": "YOUR_CLIENT_ID",
    "device_code": "DEVICE_CODE",
    "code_verifier": "CODE_VERIFIER"
  }'

Пока пользователь не подтвердил — 400 с одним из состояний:

После подтверждения тот же запрос отдаёт 200 с ключом и двумя наборами прав:

{ "api_key": "vibe_api_...", "scopes": ["crm"], "granted_scopes": ["crm"] }

Обратите внимание: здесь объект уже, чем в основном потоке, — без блоков portal и user.

Ключ отдаётся один раз. Повторный опрос тем же device_code вернёт expired_token, поэтому сохраняйте ключ сразу.

Что обязано уметь устройство

• Показывать обратный отсчёт. Код живёт 15 минут; по истечении показать новый, а не мёртвый экран.
• Соблюдать interval и реагировать на slow_down. Опрос чаще разрешённого не ускорит выдачу, а приведёт к отказам.
• Не показывать device_code. На экран идёт только user_code.

Использование API-ключа

Полученный ключ имеет тип APP и работает как стандартный API-ключ Вайбкод. Передавайте его в заголовке X-Api-Key:

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

Один и тот же ключ можно использовать с любым эндпоинтом Вайбкод API в пределах подтверждённых скоупов: список сделок, batch-запросы, агрегация и т. д.

Партнёрскому ключу платформенные скоупы vibe:ai (AI-роутер) и vibe:search (веб-поиск) не добавляются — ключ несёт ровно те права, которые пользователь подтвердил на странице согласия. Поэтому вызовы AI-роутера (/v1/chat/completions) и веб-поиска (/v1/search) через партнёрский ключ по умолчанию возвращают 403.

Партнёрский ключ работает с одним заголовком X-Api-Key и не требует Authorization: Bearer <session_token>. По префиксу его видно сразу: партнёрский ключ начинается с vibe_api_, а ключ OAuth-приложения из каталога Вайбкод — с vibe_app_, и для второго сессия пользователя обязательна.

Доступные скоупы

При вызове /v1/connect/authorize передавайте те же скоупы, что и при создании стандартного API-ключа в портале Битрикс24. На странице согласия пользователь видит список запрошенных прав и подтверждает его целиком — снять отдельный пункт нельзя, доступны только «Разрешить» и «Отклонить». Итоговый набор приходит в поле granted_scopes ответа /v1/connect/token, а запрошенный — в поле scopes рядом.

Актуальный перечень поддерживаемых значений описан в разделе Ключи и авторизация — он пополняется по мере появления новых модулей Битрикс24, поэтому здесь не дублируется.

Платформенные права Вайбкод (vibe:ai, vibe:search, vibe:infra, vibe:storage, vibe:feedback) через саморегистрацию запросить нельзя — см. Регистрация партнёра.

Время жизни и отзыв ключа

• Код авторизации (code) действует 5 минут и одноразовый. После обмена через /v1/connect/token повторный вызов с тем же кодом вернёт invalid_grant.

• Стейт согласия (внутреннее состояние страницы согласия) живёт 10 минут — если пользователь не подтвердит за это время, ссылку придётся выдавать заново.

• API-ключ не имеет срока истечения. Действует, пока его не отзовут. Отзыв происходит одним из трёх способов:

  1. Пользователь отзывает доступ сам — раздел «Подключённые приложения» в его профиле Вайбкод. Это гасит все ключи, которые он выдал вашему приложению для этого портала, включая ключи от прежних авторизаций. Доступы других сотрудников того же портала не затрагиваются.
  2. Владелец приложения полностью удаляет клиента — вызовом DELETE /api/connect/clients/:id?purge=true (клиент должен быть предварительно деактивирован); гасятся все ключи, выданные этим клиентом. В кабинете доступна только деактивация — ключи она не трогает.
  3. Платформенный администратор отзывает выданные клиентом ключи.

  Деактивация клиента ключи НЕ отзывает — она только закрывает выдачу новых: с неактивным клиентом /v1/connect/authorize отклонит запрос, а уже выданные ключи продолжат работать.

При отзыве ключа все запросы с ним возвращают 401 KEY_INACTIVE. Если ключ удалён или неизвестен — 401 INVALID_API_KEY. Партнёр должен корректно обработать оба кода и предложить пользователю повторно авторизоваться.

Безопасность

• State-параметр — генерируйте криптостойкую случайную строку на каждый запрос и сверяйте при возврате на redirect_uri. Защищает от CSRF.
• client_secret — только на сервере. Никогда не передавайте секрет в браузер, мобильное приложение или клиентский код. Обмен кода на ключ выполняется только серверным запросом.
• Хранение ключа. API-ключ — секрет, который даёт доступ к данным пользователя. Храните в зашифрованном виде, ограничивайте доступ к строке подключения, не логируйте.
• Привязка redirect_uri. Значение в /v1/connect/authorize и /v1/connect/token должно совпадать символ в символ — несоответствие приведёт к invalid_grant.

Регистрация партнёра

Клиент регистрируется самостоятельно в кабинете Вайбкод — раздел Connect-приложения, боковое меню, группа «Доступ». Войдите под учётной записью Вайбкод и нажмите «Зарегистрировать приложение» — client_id выдаётся сразу, без заявки и предварительной проверки.

В форме заполняются:

• название и краткое описание приложения,
• идентификатор — строчные латинские буквы, цифры и дефис,
• один или несколько redirect_uri — адреса https:// либо локальные 127.0.0.1 и localhost,
• запрашиваемые права доступа.

Набор прав не может быть пустым: регистрация без единого права возвращает EMPTY_SCOPES. Приложение без прав не может запросить у пользователя ничего.

Тип клиента выбирается при создании и позже не меняется — разбор с примерами в разделе Типы клиента.

client_secret показывается один раз при создании. Прочитать его повторно нельзя, только перевыпустить действием «Обновить секрет».

В ⋮-меню карточки приложения есть два помощника: «Собрать ссылку» — конструктор ссылки авторизации (выбор redirect_uri и прав, готовый URL и curl для обмена кода, для клиента без секрета — одноразовая пара строк PKCE), и «Как увидит клиент» — превью страницы согласия ровно в том виде, в каком её увидит пользователь, включая бейдж верификации.

Платформенные скоупы vibe:ai, vibe:search, vibe:infra, vibe:storage и vibe:feedback при саморегистрации недоступны — запрос с ними отклоняется кодом SCOPE_NOT_ALLOWED. Их выдаёт платформенный администратор проверенному приложению.

Число активных клиентов на одного пользователя ограничено. При достижении предела регистрация возвращает CLIENT_LIMIT_REACHED, текущее значение приходит в поле limit. Деактивация клиента освобождает место.

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

Что снимает отметку «проверено»

Отметка держится на том, каким приложение прошло проверку, поэтому правка четырёх полей возвращает статус «непроверенное»:

• название,
• логотип,
• адреса возврата redirect_uri,
• набор запрашиваемых прав.

Описание и адрес сайта на отметку не влияют.

Кабинет предупреждает до сохранения: форма показывает подтверждение с перечнем полей, из-за которых отметка будет снята. Без подтверждения правка не сохраняется, ответ — VERIFICATION_RESET_NOT_CONFIRMED с тем же перечнем в теле.

Заполнение пустого набора прав отметку не снимает, когда выбранные права укладываются в набор, выданный администратором.

Сброс касается только отметки. Выданные ключи, подключённые пользователи, платформенные права и разрешённый вход по коду устройства сохраняются. Заявку на проверку подают заново.

Типы клиента

Тип отвечает на один вопрос: есть ли у приложения место, недоступное пользователю, где можно хранить секрет. От ответа зависит, выдаётся ли client_secret.

Конфиденциальный

У приложения есть серверная часть. client_secret лежит там и никогда не попадает в браузер или на устройство пользователя.

Примеры: SaaS-сервис аналитики, который ходит в портал клиента по расписанию. Синхронизация с 1С на вашем сервере. Чат-ассистент, который принимает вебхуки и отвечает от своего бэкенда.

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

Публичный

Секрет спрятать негде — код целиком выполняется на устройстве пользователя. client_secret не выдаётся, вместо него подлинность подтверждает PKCE: приложение генерирует на каждый запуск потока случайную строку, отправляет в /v1/connect/authorize её хеш, а в /v1/connect/token — саму строку. Перехваченный код без неё не обменивается.

Примеры: мобильное приложение. Десктопная программа. Одностраничное веб-приложение без собственного бэкенда.

Как выбрать

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

Тип задаётся один раз при регистрации. Чтобы сменить его, зарегистрируйте нового клиента.

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

• Ключи и авторизация
• Управляющие ключи
• Ошибки API