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
ParameterbotId Typenumber Requiredyes DescriptionBot 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
Fielddata.validated Typeboolean Descriptiontrue if the bot's credentials are valid
Fielddata.refreshed Typeboolean Descriptiontrue 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
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP404 CodeBOT_NOT_FOUND DescriptionBot not found
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to a different API key. To regain control — Bot access recovery
HTTP409 CodeBOT_REAUTH_NOT_ALLOWED DescriptionThe disabled state does not allow re-authorization; do not retry the call
HTTP409 CodeBOT_REAUTH_STATE_CHANGED DescriptionBot ownership or state changed during the probe; re-read state before deciding manually
HTTP410 CodeREAUTH_REQUIRED DescriptionAccess is invalid and cannot be recovered automatically. What to do depends on error.details.credentialKind
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP401 CodeTOKEN_MISSING DescriptionThe 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
credentialKindwebhook What it meansThe 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 What to doRe-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
credentialKindoauth What it meansThe key does have an authorization flow, but the refresh token is invalid too What to doRe-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