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

Перепривязать приложение

POST /v1/apps/:id/relink-oauth

Заменяет учётные данные OAuth-приложения Битрикс24 у существующей записи: сама запись, её ключ авторизации и связанный бот остаются на месте. Вызов нужен, когда локальное OAuth-приложение на аккаунте пересоздали и у него сменились идентификатор и секрет.

Параметры

Параметр Тип Обяз. Описание
id (path) string да Идентификатор приложения. Список: GET /v1/apps

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

Поле Тип Обяз. Описание
bitrixClientId string да Идентификатор OAuth-приложения на аккаунте Битрикс24 — значение client_id пересозданного локального приложения. От 1 до 255 символов, допустимы латинские буквы, цифры, точка, дефис и подчёркивание
bitrixClientSecret string да Секрет того же OAuth-приложения. От 1 до 255 символов. В ответе не возвращается и в журналы платформы не записывается

Обновление токена доступа читает идентификатор и секрет вместе, поэтому замена одного идентификатора оставила бы обновление токена нерабочим.

Примеры

Перепривязку выполняет личный ключ vibe_api_… автора приложения или администратора аккаунта. Ключ OAuth-приложения vibe_app_… получает на этом вызове 403 OAUTH_APP_KEY_CANNOT_RELINK, поэтому примеров с ним нет.

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/apps/YOUR_APP_ID/relink-oauth" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bitrixClientId": "local.9f8e7d6c5b4a30.11112222",
    "bitrixClientSecret": "NEW_CLIENT_SECRET"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/apps/YOUR_APP_ID/relink-oauth',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      bitrixClientId: 'local.9f8e7d6c5b4a30.11112222',
      bitrixClientSecret: 'NEW_CLIENT_SECRET',
    }),
  }
)
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log(body.data.bitrixClientId)

Поля ответа

Поле Тип Описание
success boolean true при успешной перепривязке
data object Приложение после перепривязки — те же поля, что отдают данные приложения
data.bitrixClientId string Идентификатор OAuth-приложения, переданный в запросе
data.updatedAt string Дата изменения записи, ISO 8601

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

JSON 
{
  "success": true,
  "data": {
    "id": "33c4d5e6-f7a8-49b0-1234-5c6d7e8f9012",
    "title": "Дашборд продаж",
    "description": null,
    "scopes": ["crm", "user", "placement"],
    "handlerUrl": "https://vibecode.bitrix24.tech/v1/bitrix-handler",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.tech",
    "redirectUris": [
      "https://vibecode.bitrix24.tech/oauth/complete",
      "http://localhost"
    ],
    "bitrixClientId": "local.9f8e7d6c5b4a30.11112222",
    "prefix": "vibe_app_local_7c3",
    "suffix": "6666",
    "authorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "portalId": "8b1f0e2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "createdAt": "2026-06-24T09:12:45.781Z",
    "updatedAt": "2026-08-25T09:46:02.117Z",
    "placements": [],
    "catalogStatus": "PRIVATE",
    "publishedAt": null,
    "placementResizeEnabled": false
  }
}

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

404 — приложения с таким идентификатором нет:

JSON 
{
  "success": false,
  "error": {
    "code": "APP_NOT_FOUND",
    "message": "Application not found"
  }
}

Ошибки

HTTP Код Описание
400 VALIDATION_ERROR Тело не прошло проверку схемы: пропущено одно из полей либо значение вышло за пределы длины или набора допустимых символов. message перечисляет поля
403 INFRA_FORBIDDEN_FOR_COWORK_KEY Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — Проектный ключ для деплоя
403 OAUTH_APP_KEY_CANNOT_RELINK Вызов сделан ключом OAuth-приложения vibe_app_…, в том числе ключом самого перепривязываемого приложения. Такой ключ переставить учётные данные не может — возьмите личный ключ vibe_api_…
403 UNAUTHORIZED Запрос не от автора приложения и не от администратора аккаунта
403 WRITE_BLOCKED_READONLY_KEY Ключ в режиме «только чтение» вызвал метод записи
404 APP_NOT_FOUND Приложения с таким идентификатором нет на аккаунте ключа, оно удалено или это служебное приложение платформы. Идентификатор проверяется до разбора тела, поэтому неизвестный идентификатор отвечает 404 и при пустом теле
409 OAUTH_CLIENT_ID_IN_USE Переданный bitrixClientId уже привязан к другому приложению. Проверка глобальная — занятым считается идентификатор, привязанный к приложению на любом аккаунте, включая удалённые записи

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

Известные особенности

  • Приложение устанавливается на аккаунте заново. Перепривязка очищает токены, которые пользователи выдали прежнему OAuth-приложению, — при любых новых учётных данных, даже когда меняется только секрет. Открытые сессии мест встраивания на этом прекращаются, а публикация до повторной авторизации отвечает NO_USER_TOKEN. Порядок авторизации — Авторизация пользователей приложения.
  • Смена идентификатора снимает подписки на события аккаунта. Регистрации, сделанные прежним OAuth-приложением, после смены bitrixClientId не срабатывают, поэтому платформа удаляет их записи — подпишитесь заново через подписки на события портала. Запрос с прежним bitrixClientId меняет только секрет и подписки сохраняет.

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