For AI agents: markdown of this page — /docs-content-en/bots/management/reauth.md documentation index — /llms.txt

Bot re-authorization

POST /v1/bots/:botId/reauth

Validates the bot's credentials and refreshes the access token if needed. The call is allowed for an active bot after ownership transfer and for 410 BOT_DISABLED only when the response includes error.details.reauthAllowed=true. Other disabled states are protected and return 409 BOT_REAUTH_NOT_ALLOWED. No request body is required.

Parameters

Parameter Type Required Description
botId number yes Bot ID (path parameter)

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/reauth \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/reauth \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/reauth', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log(data) // { validated: true, refreshed: false }

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/reauth', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

Response fields

Field Type Description
data.validated boolean true if the bot's credentials are valid
data.refreshed boolean true if the access token was refreshed during the check

Response example

JSON 
{
  "success": true,
  "data": {
    "validated": true,
    "refreshed": false
  }
}

Error response example

410 — credentials are invalid and cannot be recovered automatically:

JSON 
{
  "success": false,
  "error": {
    "code": "REAUTH_REQUIRED",
    "message": "Bot credentials are invalid. This key authorizes through a Bitrix24 inbound webhook, so there is no OAuth flow to re-run — the webhook itself is dead, most often deleted on the Bitrix24 side. Repair it from the VibeCode cabinet: an ordinary personal key is re-minted on the Keys page (the key id and string are preserved, so linked bots keep working), and an agent-owned key is repaired from the agent card, which the platform routes to POST /api/agents/:id/recover-key. This API key cannot perform either action itself — both are session-authenticated cabinet routes.",
    "details": {
      "statusCode": 401,
      "bitrixErrorCode": "INVALID_CREDENTIALS",
      "credentialKind": "webhook"
    }
  }
}

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND Bot not found
403 BOT_ACCESS_DENIED The bot belongs to a different API key. To regain control — Bot access recovery
409 BOT_REAUTH_NOT_ALLOWED The disabled state does not allow re-authorization; do not retry the call
409 BOT_REAUTH_STATE_CHANGED Bot ownership or state changed during the probe; re-read state before deciding manually
410 REAUTH_REQUIRED Access is invalid and cannot be recovered automatically. What to do depends on error.details.credentialKind
403 SCOPE_DENIED The API key does not have the imbot scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

When to use. Automatically, only when the BOT_DISABLED response includes the boolean error.details.reauthAllowed=true. Manually, the endpoint also validates an active bot after an ownership transfer. Do not call it for every BOT_DISABLED: when reauthAllowed=false, the server returns BOT_REAUTH_NOT_ALLOWED.

The refreshed field. It is true only for an authorization key with an expired access token: the check refreshes the token in the process. For a personal key, refreshed is always false.

The 410 response and the credentialKind field. Automatic recovery is impossible, but the remedy depends on how the key authorizes against Bitrix24. The class is returned in error.details.credentialKind:

credentialKind What it means What to do
webhook The key authorizes through a Bitrix24 inbound webhook. It has no authorization flow and no refresh token — the webhook itself is dead, most often deleted on the Bitrix24 side Re-mint the webhook in your Vibecode account. For an ordinary personal key this happens on the API Keys page: the key ID and string are preserved, so linked bots keep working. An agent-owned key is repaired from the agent card
oauth The key does have an authorization flow, but the refresh token is invalid too Re-authorize the key through POST /v1/oauth/authorize, or recreate the personal key

Both actions run in your Vibecode account and require a session — an API key cannot perform them itself.

See also