Management keys

Management keys (vibe_live_) are not tied to a single Bitrix24 account and are intended for automating administration: managing API keys, viewing Bitrix24 accounts, and working with feedback.

Difference from Bitrix24 account keys

Management key scopes

Each management key is created with one or more scopes. Without the required scope, the endpoint returns 403 MANAGEMENT_SCOPE_REQUIRED — even if the endpoint is otherwise available to management keys.

The endpoints /v1/me, /v1/guide, and /v1/openapi.json are available to any management key without a separate scope.

When creating a key, select only the scopes you need — if the key is intended only for managing API keys, it does not need the vibe:mgmt:feedback scope.

Key owner's account state

A management key acts on behalf of its owner, so the state of the owner's account is checked on every endpoint available to management keys — on reads and on writes alike. The check runs before the scope check, so these codes arrive even where the key lacks the required scope.

The freeze covers every management-key operation, including issuing, rotating and deleting API keys.

Available endpoints

Calls to Bitrix24 entity endpoints return 403 MANAGEMENT_KEY_NO_ENTITY_ACCESS.

`GET /v1/me` — key self-description

Returns the key type, the list of Bitrix24 accounts with roles and key counts, the list of available endpoints, and a quickstart.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.com/v1/me

Response:

{
  "success": true,
  "data": {
    "type": "management",
    "keyPrefix": "vibe_live_abc123",
    "keySuffix": "f9d2",
    "expiresAt": null,
    "scopes": [],
    "capabilities": [
      "GET https://vibecode.bitrix24.com/v1/me — this endpoint (management key self-description)",
      "GET https://vibecode.bitrix24.com/v1/guide — full API reference (portal-agnostic)",
      "GET https://vibecode.bitrix24.com/v1/keys — list APP keys for a portal (requires portalId query param)",
      "POST https://vibecode.bitrix24.com/v1/keys — create APP key (requires portalId in body)",
      "GET https://vibecode.bitrix24.com/v1/portals — list your portals",
      "GET https://vibecode.bitrix24.com/v1/feedback — list ALL platform feedback (management key sees everything)",
      "GET https://vibecode.bitrix24.com/v1/feedback/:id — feedback details including comment thread",
      "PATCH https://vibecode.bitrix24.com/v1/feedback/:id — update status/resolution (legacy, prefer /comments)",
      "POST https://vibecode.bitrix24.com/v1/feedback/:id/comments — post a team comment, changes status"
    ],
    "portals": [
      {
        "id": "portal-uuid",
        "domain": "mycompany.bitrix24.com",
        "status": "ACTIVE",
        "role": "ADMIN",
        "appKeyCount": 3
      }
    ],
    "totalAppKeys": 3,
    "quickstart": {
      "step1": "GET https://vibecode.bitrix24.com/v1/portals — list available portals",
      "step2": "GET https://vibecode.bitrix24.com/v1/keys?portalId=<id> — list APP keys for a portal",
      "step3": "POST https://vibecode.bitrix24.com/v1/keys { portalId, name, scopes } — create an APP key",
      "step4": "Use the APP key for entity API calls (deals, tasks, etc.)"
    },
    "docs": "https://vibecode.bitrix24.com/docs/management-keys"
  }
}

The response also contains a feedback object that lists the endpoints, statuses, and filters for working with feedback tickets — it is used by AI models to process tickets automatically.

`GET /v1/guide` — API reference

Returns the full API reference with all entities (no scope filtering). Used to pick the required endpoints before creating API keys.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.com/v1/guide

`GET /v1/openapi.json` — OpenAPI specification

Returns the machine-readable OpenAPI 3.1 specification of the Vibecode platform.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.com/v1/openapi.json

`GET /v1/portals` — Bitrix24 account list

Returns the Bitrix24 accounts the user has access to, along with the user's role in each.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.com/v1/portals

`GET /v1/keys` — API key list for a Bitrix24 account

The portalId parameter is required. The response lists the management key owner's keys in the specified Bitrix24 account — both personal vibe_api_ keys and authorization vibe_app_ keys. Key values are never returned: you recognize your own key in the list by its prefix and suffix fields.

curl -H "X-Api-Key: vibe_live_abc123..." \
  "https://vibecode.bitrix24.com/v1/keys?portalId=portal-uuid"

{
  "success": true,
  "data": [
    {
      "id": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33",
      "name": "Support bot",
      "prefix": "vibe_api_XXXXXXXXX",
      "suffix": "XXXX",
      "type": "APP",
      "userId": "a02e7b64-91c3-4f5a-8d20-7e1b3c95a4dc",
      "portalId": "d41f0b93-6c85-42e7-9a13-58bd0e7c2f46",
      "clientId": null,
      "scopes": ["imbot"],
      "ipWhitelist": [],
      "rateLimit": null,
      "status": "ACTIVE",
      "accessMode": "READWRITE",
      "issuedVia": "legacy",
      "expiresAt": null,
      "lastUsedAt": "2026-07-29T09:12:44.301Z",
      "createdAt": "2026-07-14T08:03:17.118Z",
      "updatedAt": "2026-07-14T08:03:17.118Z"
    }
  ]
}

Rejections of this request:

`POST /v1/keys` — create an API key

Creates a new API key (vibe_api_) for the specified Bitrix24 account. Pass portalId, a name, and a list of scopes in the body. The full key is returned in the rawKey field once — save it immediately.

curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"portalId": "portal-uuid", "name": "My Key", "scopes": ["crm", "task"]}' \
  https://vibecode.bitrix24.com/v1/keys

By default four platform scopes are added to the requested ones: vibe:infra, vibe:ai, vibe:search, vibe:storage. The key in the example above gets crm, task, and those four.

On an account where the administrator has turned server management off, vibe:infra is silently dropped from that default — the key is issued with the other three. The 403 INFRA_DISABLED_FOR_PORTAL refusal comes back only for an explicitly requested scope.

To get a key with exactly the scopes you listed, pass exactScopes: true:

curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"portalId": "portal-uuid", "name": "Storage only", "scopes": ["crm", "vibe:storage"], "exactScopes": true}' \
  https://vibecode.bitrix24.com/v1/keys

Such a key gets only crm and vibe:storage, and answers 403 to POST /v1/infra/servers and to AI calls. Its scopes are treated as final: the platform does not widen them at request time, so GET /v1/me returns exactly what was stored at issue time.

Additional error codes:

The 403, 409, 410 and 502 issuance refusals from the table above also arrive on POST /v1/keys/:id/rotate — both methods issue the key through the same path. The exception is 403 PORTAL_TARIFF_UNREADABLE: it is an outcome of the platform access check, which does not apply to rotation. A 402 reaches rotation only from the issuance itself — the second check described below — because the platform access check does not apply to rotation. The body of such a refusal carries an optional error.reason field with the exact cause in the platform's taxonomy, while error.code stays as it was. Branch on error.code, not on the message text.

The 402 INT_TARIFF_REQUIRED refusal comes from the Bitrix24 account access check: a commercial Bitrix24 plan grants full access, a trial plan grants limited access, and an account on a free plan is refused. That check applies to issuing a new key only: rotation via POST /v1/keys/:id/rotate, automatic key recovery and ownership handover are not subject to it, and already issued keys keep working. The same check has one outcome with status 403: when the account plan could not be read at all, it answers PORTAL_TARIFF_UNREADABLE, and in that state the platform has nothing to name as the required plan.

A second check runs later, and its reach is WIDER: Bitrix24 itself refuses the issuance because the account plan does not include Vibecode. It fires on everything that actually issues a key — creation, rotation via POST /v1/keys/:id/rotate, automatic key recovery and ownership handover. Where access can be purchased, the answer is 402 INT_VIBE_PLUS_REQUIRED; where there is nothing to offer, it is 502 CONNECTOR_PLAN_REQUIRED from the table above. Either code is terminal: retrying will not help until the Bitrix24 plan changes.

The placement, entity, and userfieldtype scopes are not kept on the success path either: a created personal key does not return them in the response scopes, even when they were sent alongside data scopes. userfieldconfig remains available.

`GET /v1/keys/:id` — single key data

Returns a single key record without its value. The field set is the same as for GET /v1/keys above.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.com/v1/keys/key-uuid

`PATCH /v1/keys/:id` — update a key

Any of the fields below can be changed (all optional — pass only what you are changing):

The new scopes list goes through the same check as on creation: if no data scope is left once placement, entity, and userfieldtype are dropped, 400 PERSONAL_KEY_WEBHOOK_SCOPES_INVALID arrives.

Keys the platform issues on its own endpoints come back into service under special rules. A key billed against the subscription is made active again through status and extended through expiresAt only while the issuance checks pass: a failing check answers 403 with its own code — the same five as on rotation; their table is in the POST /v1/keys/:id/rotate section below. The other such keys — a Cowork/Code desktop key, an agent key, a project deploy key — do not come back into service here at all: they are issued again where they were issued.

Shortening the expiry, revoking and editing the other fields work as before — they stop a key rather than hand one out. Ordinary dashboard keys are unaffected by these checks.

curl -X PATCH \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"status": "REVOKED"}' \
  https://vibecode.bitrix24.com/v1/keys/key-uuid

`DELETE /v1/keys/:id` — delete a key

Deletes the key. If the key has active servers, 409 KEY_HAS_ACTIVE_SERVERS is returned — the servers must be deleted first. If an agent, a managed bot, or a regular chat-bot, including a disabled Bot Platform row, is managed through the key, deletion returns 409 KEY_HAS_LINKED_AGENT with details.linkedAgentCount, details.linkedBotCount (managed + regular chat-bots), a details.agents list, and details.bots (up to 10 regular chat-bots). For DELETE /v1/bots/:botId, take the numeric bitrixBotId from the matching details.bots item in the 409 response.

curl -X DELETE \
  -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.com/v1/keys/key-uuid

`POST /v1/keys/:id/rotate` — rotate a key

Creates a new key with the same settings and gives the old one a 24-hour transition period. After rotation, the old key automatically becomes invalid. The scopes are carried over from the previous key as they are — a new set is not passed here.

If the previous Bitrix24 account key is left with only application-context scopes — placement, entity, userfieldtype — rotation fails. The scope set is checked before the account is contacted, so every account receives the same refusal, 400 PERSONAL_KEY_WEBHOOK_SCOPES_INVALID. Add a data scope to the previous key through PATCH /v1/keys/:id first.

Rotation is subject to the same Bitrix24 plan requirement as key creation: on an account whose plan does not grant access, it answers 403 INT_TARIFF_REQUIRED. Every other issuance refusal is the same as on creation — see the code table under POST /v1/keys above. Only the 402 variant of INT_TARIFF_REQUIRED is out of scope for rotation: the platform access check applies to issuing a new key. Already issued keys keep working, and rotation resumes as soon as the account is on a qualifying plan.

curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.com/v1/keys/key-uuid/rotate

Keys the platform issues on its own endpoints rotate under special rules. For a key billed against the subscription, the scope carry-over is not unconditional: before rotation the same checks run as when the key was issued, and a failing check answers 403 with its own code. The other such keys — a Cowork/Code desktop key, an agent key, a project deploy key — are not rotated here at all: they are issued again where they were issued. In all these cases the previous key keeps working.

Ordinary dashboard keys are unaffected by these checks — they rotate as before. What a subscription key can do and how to issue one — Your own agent on the subscription.

`GET /v1/feedback` — feedback ticket list

Returns all feedback tickets on the platform. Supports filters by status, category, and Bitrix24 account, plus pagination.

curl -H "X-Api-Key: vibe_live_abc123..." \
  "https://vibecode.bitrix24.com/v1/feedback?status=NEW&page=1&limit=50"

`GET /v1/feedback/:id` — ticket card

Returns the ticket with the full comment thread.

`PATCH /v1/feedback/:id` — update a ticket

Changes the ticket status and resolution.

`POST /v1/feedback/:id/comments` — comment on a ticket

Adds a team comment to the thread and changes the status at the same time. Used by AI models to reply to the user.

Ticket statuses

A user's reply moves a ticket out of AWAITING_USER into NEEDS_REVIEW. A resolved ticket (RESOLVED) is brought back into the queue by an author reply — the status also becomes NEEDS_REVIEW, the closure stamp (resolvedAt, resolvedBy) is cleared, and the resolution text is kept. On NEW, REVIEWING and NEEDS_REVIEW the status is preserved, because the next move is the team's anyway. The updatedAt field is always refreshed, so a queue sorted by it surfaces new replies regardless of status.

Ticket categories

BUG, SUGGESTION, DOCS, CHAT, BOTS, OTHER.

List filters

?status=NEW&category=BUG&portalId=<uuid>&page=1&limit=50. The limit parameter is capped at 100.

Quickstart

1. Create a management key in the Vibecode dashboard (the "Management Keys" section)
2. Get the Bitrix24 account list: GET /v1/portals
3. View the existing keys in the target Bitrix24 account: GET /v1/keys?portalId=<id>
4. Create an API key with the required scopes: POST /v1/keys { portalId, name, scopes }
5. Use the resulting API key (vibe_api_…) to work with Bitrix24 data

Limitations

• Management keys cannot call Bitrix24 entity endpoints (/v1/deals, /v1/tasks, and others)
• To work with data, use an API key (vibe_api_) or an authorization key (vibe_app_)
• An attempt to call an unsupported endpoint returns 403 MANAGEMENT_KEY_NO_ENTITY_ACCESS

See also

• Keys and authorization
• Rights to create keys and apps
• Scopes
• Quickstart
• Limits and optimization
• Error codes
• Bot access recovery