For AI agents: markdown of this page — /docs-content-en/apps/relink-oauth.md documentation index — /llms.txt

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
Parameterid (path) Typestring Requiredyes DescriptionApplication identifier. List: GET /v1/apps

Request fields (body)

Field Type Required Description
FieldbitrixClientId Typestring Requiredyes DescriptionIdentifier 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
FieldbitrixClientSecret Typestring Requiredyes DescriptionSecret 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

Terminal 
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
Fieldsuccess Typeboolean Descriptiontrue on a successful relink
Fielddata Typeobject DescriptionThe application after relinking. For the full object structure, see Application data

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
HTTP400 CodeVALIDATION_ERROR DescriptionThe 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
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionThe call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see Project key for deploy
HTTP403 CodeOAUTH_APP_KEY_CANNOT_RELINK DescriptionThe 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
HTTP403 CodeUNAUTHORIZED DescriptionThe request is not from the application author and not from a Bitrix24 account administrator
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe 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
HTTP404 CodeAPP_NOT_FOUND DescriptionThe 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
HTTP409 CodeOAUTH_CLIENT_ID_IN_USE DescriptionThe 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.

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 returns NO_USER_TOKEN until authorization is repeated. The authorization sequence — Application user authorization.
  • 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. A request that keeps the previous bitrixClientId changes only the secret and preserves the subscriptions.

See also