Authorization, keys and permissions

A detailed breakdown of the codes the Vibecode API returns when a key is not recognized, lacks the required permissions, or runs in read-only mode.

The summary table of all Vibecode API codes — Error codes.

`MISSING_API_KEY` (401)

The request carries no X-Api-Key header.

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Causes:

• The X-Api-Key or Authorization header was not passed.
• The header was passed with an empty value.

Fix:

• Add the X-Api-Key: vibe_api_... or X-Api-Key: vibe_app_... header.
• Verify that the environment variable holding the key is set correctly (for CLI tools and SDKs).

`INVALID_API_KEY` (401)

The passed key does not exist or its format is unrecognized.

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Causes:

• A typo or extra whitespace in the key.
• The key was deleted by its owner or an administrator.
• The key is from a different environment — staging instead of production or the other way around.
• The prefix is not among the supported ones: vibe_api_, vibe_app_, vibe_live_.

Fix:

• Check the key on the page for its kind: a personal key (vibe_api_) on API Keys, an application auth key (vibe_app_) in the application card under Applications, a management key (vibe_live_) on Management Keys. The API Keys section lists personal keys only, so a missing application or management key there does not mean it was deleted.
• Create a new key if the old one really was deleted.

`TOKEN_MISSING` (401)

The key carries no Bitrix24 credentials, so there is no way to call Bitrix24. The cause depends on the key type — these are two different scenarios.

A personal key (vibe_api_*) reaches Bitrix24 through a webhook. When the key has no webhook, the response on entity calls (/v1/{entity} and POST /v1/batch) carries a machine-readable reason in error.details. Other routes return the same code without details:

{
  "success": false,
  "error": {
    "code": "TOKEN_MISSING",
    "message": "This personal API key (vibe_api_*) has no Bitrix24 webhook credentials, ...",
    "details": {
      "reason": "INT_TARIFF_REQUIRED",
      "paywallCode": "INT_TARIFF_REQUIRED"
    }
  }
}

Values of details.reason:

Reconnecting — POST /api/keys/:id/reconnect: issues a webhook for the key without changing the key string (no integration has to be reconfigured) and clears the auto-disable on linked bots. Not applicable to app keys, system-managed keys, or keys with no Bitrix24 scopes — those still need a new key.

Important: reconnecting is NOT available for every key: the platform refuses it with 400 RECONNECT_NOT_APPLICABLE for app keys, keys with a system-managed purpose (including the Cowork key), keys linked to a server, to a live agent or to a live managed bot, and keys with no Bitrix24 scopes. For these keys the error message does not offer reconnecting at all — the cause has to be closed on the Bitrix24 account, and the platform then mints the webhook on its own.

paywallCode arrives only for the plan-related reason and repeats it. The upgradeUrl field — a link to the upgrade page in the Bitrix24 account — never comes with INT_TARIFF_REQUIRED.

The same condition also blocks app installation and placement binding — there it arrives as a standalone 403 code, covered in Billing and plans.

An app key (vibe_app_*) keeps the Bitrix24 tokens in a per-user session, not on the key. For a call with X-Api-Key alone and no Authorization: Bearer <session token>, TOKEN_MISSING is the correct answer — this branch carries no details, and message describes the missing OAuth step. Full flow — Keys and authorization.

How to check a key's state up front: GET /v1/me for a personal key returns a b24Credentials block (ready, and when ready: false the same reason plus actions), and GET /v1/keys returns a b24Ready flag on every key. The /v1/me response is cached for 30 seconds, so right after fixing the Bitrix24 side, request it as GET /v1/me?refresh=tariff — otherwise the previous state is returned for up to half a minute. GET /v1/keys is not cached.

`PORTAL_CREDENTIALS_REJECTED` (401)

Bitrix24 rejected the credentials the platform calls the account with on behalf of this key. The difference from TOKEN_MISSING: there the key has no credentials at all, here it has them but the account no longer accepts them — the webhook was revoked, deleted on the Bitrix24 side, or lost its power together with the owner's rights.

{
  "success": false,
  "error": {
    "code": "PORTAL_CREDENTIALS_REJECTED",
    "message": "Bitrix24 rejected the credentials this key calls the portal with",
    "hint": "The portal no longer accepts the webhook or token behind this key. Reconnect the key to the portal (or re-issue it) — Retrying will not help until the credentials are restored."
  }
}

Retrying does not help: until the credentials are restored, every call this key makes is refused the same way. The code arrives on any route that reads account data, and in a POST /v1/batch sub-error.

What to do: reconnect the key — POST /api/keys/:id/reconnect — or, when reconnection does not apply to the key, create a new one. The reconnection limits are the same as for TOKEN_MISSING above.

How to tell it from a rights refusal: missing rights arrive as SCOPE_DENIED (403) and BITRIX_ACCESS_DENIED (403) — there the credentials were accepted but the operation is closed. PORTAL_CREDENTIALS_REJECTED means the account did not recognize the credentials themselves, and no scope setting changes that.

`SCOPE_DENIED` (403)

The key lacks the required scope for the requested operation.

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Causes:

• CRM entities require the crm scope, tasks require task, the bot platform requires imbot, the AI Router requires vibe:ai, infrastructure requires vibe:infra.
• The key's scope was narrowed at creation time.

Fix:

• Open the key page in your account and issue a new key with a broader scope set.
• The full list of scopes and their purpose is on the Keys and authorization page.

`BITRIX_ACCESS_DENIED` (403)

Bitrix24 returned ACCESS_DENIED: the user or app lacks permission for the entity or operation.

{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "ACCESS_DENIED"
  }
}

Causes:

• The user lacks permission for the entity in CRM (e.g. another user's deal with restricted visibility).
• The scope set in the Bitrix24 account is narrower than the key's own scope set. Bitrix24 scopes are fixed for the key at issue time, so a scope added to an already issued key shows up in GET /v1/me, while the key still accesses the account's data with its original set.
• The requested module is disabled in the Bitrix24 account (no CRM, no bot platform, and so on).

The fix depends on the key type. When the refusal comes from the scope set, error.hint names the specific case. The hint is not always present: a bare ACCESS_DENIED with no explanation from Bitrix24 may arrive without it.

• API key (vibe_api_). The scope set the key uses to call Bitrix24 is stored on the account side, separately from the set recorded on the key itself. Reissue the key, reconnect it, or create a new one with the scope selected — editing the app's permissions in the account changes nothing in this case.
• Authorization key (vibe_app_). Recreate the application with the required scope and complete authorization again. Reissuing the key does not grant a scope here.
• Chat and bot methods. For these methods the refusal is not explained by scopes alone: the key owner must be an administrator of the Bitrix24 account. Issue the key under an administrator account — widening the scopes will not help here.
• If the cause is the employee's permissions rather than the key's scopes, check the user's permissions in the Bitrix24 entity card.

For the full description of how scopes are fixed to a key, and what to do if the refusal repeats after a reissue, see Keys and authorization.

`WRITE_BLOCKED_READONLY_KEY` (403)

The key is in read-only mode (accessMode: "READONLY"), but the request performs a write. The mode, how to switch it, and the Bitrix24 account policy are described in full in Access mode.

{
  "success": false,
  "error": {
    "code": "WRITE_BLOCKED_READONLY_KEY",
    "message": "Key is in read-only mode. Switch to read+write in /keys to enable writes.",
    "details": {
      "method": "crm.item.add",
      "keyName": "MCP key",
      "currentMode": "READONLY",
      "switchUrl": "/keys"
    }
  }
}

Important: switchUrl is not a constant. The example above is a personal key, so the path points to the keys page. The API Keys section lists personal keys only, by design, so every other kind has a different path: for an application auth key (vibe_app_*) it is the Applications page — /applications; for a management key (vibe_live_*), /management-keys. Read the value from the response instead of hardcoding one.

details fields:

Causes:

• An API key or authorization key (vibe_api_, vibe_app_) in READONLY mode made a call that proxies to Bitrix24 as a write operation: create, update, delete, an action on an entity.
• A management key (vibe_live_) in READONLY mode made a request with the POST, PATCH, PUT, or DELETE HTTP method — e.g. an attempt to create a key via POST /v1/keys or delete a feedback record.

Fix:

• The owner of a personal key (vibe_api_) should open API Keys, select "Read and write" in the Access mode block of the relevant key's card, and save. The mode takes effect on the next request — no reissue needed.
• The owner of a management key (vibe_live_) should open Management Keys and switch the mode in the key's card. The API Keys section never lists such a key, by design, so the step above does not apply to it.
• The owner of an application auth key (vibe_app_) should open Applications and switch the mode in the Access mode block of the application card. The API Keys section never lists such a key, by design, so the step above does not apply to it. The address of the right page always arrives in details.switchUrl — follow it instead of a hardcoded path.
• If the toggle in the card is unavailable, the Bitrix24 account administrator has restricted the mode. Ask the administrator to lift the restriction for this key.
• When working through an AI agent, the effective mode is returned by GET /v1/me in the data.accessMode field. If writes are needed permanently, issue a separate key in "read and write" mode.

See also

• Error codes
• Billing and plans
• Keys and authorization
• Access mode
• Management keys
• Scopes
• Retries and error handling in code
• Rights to create keys and apps