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

`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 — личный ключ

```bash
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 | Приложение после перепривязки — те же поля, что отдают [данные приложения](/docs/apps/get) |
| `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 — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 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 — [Ошибки](/docs/errors).

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

- **Приложение устанавливается на аккаунте заново.** Перепривязка очищает токены, которые пользователи выдали прежнему OAuth-приложению, — при любых новых учётных данных, даже когда меняется только секрет. Открытые сессии мест встраивания на этом прекращаются, а [публикация](/docs/apps/publish) до повторной авторизации отвечает `NO_USER_TOKEN`. Порядок авторизации — [Авторизация пользователей приложения](/docs/keys-auth/oauth).
- **Смена идентификатора снимает подписки на события аккаунта.** Регистрации, сделанные прежним OAuth-приложением, после смены `bitrixClientId` не срабатывают, поэтому платформа удаляет их записи — подпишитесь заново через [подписки на события портала](/docs/infra/event-subscriptions). Запрос с прежним `bitrixClientId` меняет только секрет и подписки сохраняет.

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

- [Приложения](/docs/apps)
- [Данные приложения](/docs/apps/get)
- [Создать приложение](/docs/apps/create)
- [Авторизация пользователей приложения](/docs/keys-auth/oauth)
- [Подписки на события портала](/docs/infra/event-subscriptions)
- [Ошибки](/docs/errors)