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 changed.

Parameters

Parameter Type Required Description
id (path) string yes Application identifier. List: GET /v1/apps

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

The access token refresh reads the identifier and the secret together, so replacing the identifier alone would leave the refresh broken.

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
success boolean true on a successful relink
data object The application after relinking — the same fields returned by Application data
data.bitrixClientId string Identifier of the OAuth application passed in the request
data.updatedAt string Record modification date, ISO 8601

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
  }
}

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/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
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 A key in read-only mode called a write method
404 APP_NOT_FOUND No application with this identifier exists on the key's account, it was deleted, or it is a platform service application. The identifier is checked before the body is parsed, so an unknown identifier answers 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.

Known specifics

  • The application is installed on the account anew. Relinking clears the tokens users granted to the previous OAuth application — on any new credentials, even when only the secret changes. Open placement sessions end at that point, and publishing answers NO_USER_TOKEN until authorization is repeated. The authorization sequence — Application user authorization.
  • Changing the identifier drops the account event subscriptions. Registrations made by the previous OAuth application stop firing once bitrixClientId changes, so the platform deletes their records — subscribe again through Portal event subscriptions. A request that keeps the previous bitrixClientId changes only the secret and preserves the subscriptions.

See also