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. Lifts the automatic disabling if access is valid again. 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 refreshed automatically:

JSON 
{
  "success": false,
  "error": {
    "code": "REAUTH_REQUIRED",
    "message": "Bot credentials are invalid and could not be refreshed automatically — the refresh token is itself dead. Re-authorize the API key via the OAuth flow (POST /v1/oauth/authorize on an OAuth-app key, or recreate the personal key)."
  }
}

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
410 REAUTH_REQUIRED Access is invalid and cannot be refreshed automatically — the key must be re-authorized
403 SCOPE_DENIED The API key does not have the imbot scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

When to use. The bot is disabled with status BOT_DISABLED and reason AUTH_FAILURES. The check confirms access and lifts the disabling — after a successful response the bot accepts events and sends messages again.

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

The 410 response. When the refresh token is also invalid, automatic recovery is impossible — the key must be re-authorized via OAuth or the personal key recreated.

See also