## Relink an application

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

Replaces the Bitrix24 OAuth application credentials on an existing record: the record itself, its authorization key and the linked bot stay in place. Call it when the local OAuth application on the account has been recreated and its identifier and secret have changed.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `id` (path) | string | yes | Application identifier. List: [GET /v1/apps](/docs/apps/list) |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `bitrixClientId` | string | yes | Identifier of the OAuth application on the Bitrix24 account — the `client_id` of the recreated local application. From 1 to 255 characters; Latin letters, digits, dot, hyphen and underscore are allowed |
| `bitrixClientSecret` | string | yes | Secret of the same OAuth application. From 1 to 255 characters. It is not returned in the response and is not written to the platform logs |

Refreshing an access token requires both the identifier and the secret, so replacing the identifier alone would prevent token refresh.

## Examples

Relinking requires a personal `vibe_api_…` key that belongs to the application author or to a Bitrix24 account administrator. An OAuth application key `vibe_app_…` receives `403 OAUTH_APP_KEY_CANNOT_RELINK` on this call, so there are no examples with it.

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/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 — personal key

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/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)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on a successful relink |
| `data` | object | The application after relinking. For the full object structure, see [Application data](/docs/apps/get#response-fields) |

## Response example

```json
{
  "success": true,
  "data": {
    "id": "33c4d5e6-f7a8-49b0-1234-5c6d7e8f9012",
    "title": "Sales dashboard",
    "description": null,
    "scopes": ["crm", "user", "placement"],
    "handlerUrl": "https://vibecode.bitrix24.com/v1/bitrix-handler",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com",
    "redirectUris": [
      "https://vibecode.bitrix24.com/oauth/complete",
      "http://localhost"
    ],
    "bitrixClientId": "local.9f8e7d6c5b4a30.11112222",
    "prefix": "vibe_app_local_7c3",
    "suffix": "6666",
    "authorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "authorBitrixUserId": 42,
    "authorBitrixUserIdSource": "member",
    "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,
    "mobile": false,
    "hosting": "platform",
    "externalHost": null,
    "externalRegistrable": null
  }
}
```

## Error response example

404 — no application with this identifier:

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

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | The body failed schema validation: one of the fields is missing, or a value falls outside the allowed length or character set. `message` lists the fields |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork key — such a key works with data only and cannot perform write operations. To issue a key that can, see [Project key for deploy](/docs/cowork/deploy-key) |
| 403 | `OAUTH_APP_KEY_CANNOT_RELINK` | The call was made with an OAuth application key `vibe_app_…`, including the key of the application being relinked. Such a key cannot swap the credentials — use a personal `vibe_api_…` key |
| 403 | `UNAUTHORIZED` | The request is not from the application author and not from a Bitrix24 account administrator |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key does not change Bitrix24 data. Relinking removes the event handlers on the Bitrix24 account and the placement sessions of all employees, so such a key cannot relink — neither its own app nor any other. To change the key's mode, open the page at the path from `error.details.switchUrl` in the Vibecode dashboard. Where the path leads for each kind of key — [Access mode](/docs/keys-auth/access-mode) |
| 404 | `APP_NOT_FOUND` | The application with this identifier does not exist on the key's account, has been deleted, or is a platform service application. The identifier is checked before the body is parsed, so a request with an unknown identifier returns `404` even with an empty body |
| 409 | `OAUTH_CLIENT_ID_IN_USE` | The `bitrixClientId` you passed is already linked to another application. The check is global — an identifier counts as taken when it is linked to an application on any account, including deleted records |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **The application is reinstalled on the account.** Relinking clears the tokens users granted to the previous OAuth application — with any new credentials, even when only the secret changes. Open placement sessions end at that point, and [publishing](/docs/apps/publish) returns `NO_USER_TOKEN` until authorization is repeated. The authorization sequence — [Application user authorization](/docs/keys-auth/oauth).
- **Changing the identifier drops the account event subscriptions.** The platform attempts to unregister the previous OAuth application's handlers before clearing local records; while an old handler still exists, its previous `application_token` is accepted alongside the new one. Subscribe again through [Bitrix24 event subscriptions](/docs/infra/event-subscriptions). A request that keeps the previous `bitrixClientId` changes only the secret and preserves the subscriptions.

## See also

- [Applications](/docs/apps)
- [Application data](/docs/apps/get)
- [Create an application](/docs/apps/create)
- [Application user authorization](/docs/keys-auth/oauth)
- [Bitrix24 event subscriptions](/docs/infra/event-subscriptions)
- [Errors](/docs/errors)