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"
    }
  ]
}

Refusals 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; with it, POST /v1/infra/servers and AI calls return 403. 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. The platform access check does not extend 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 platform 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, PORTAL_TARIFF_UNREADABLE: the account plan could not be read at all, so 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.

Adding vibe:storage requires a personal key. An application-issued key or a key of unknown origin cannot gain storage access: create a new personal key with storage access. Existing storage may be re-sent unchanged or removed; renaming and other edits remain allowed.

If a self-hosted Bitrix24 portal has moved to a new address while the key's webhook is still issued for the previous one, a scope change is refused with 409 PORTAL_ADDRESS_CHANGED. No request is sent to Bitrix24, and the key's scopes change neither on the Vibecode platform nor in Bitrix24. Reconnect the key and repeat the change — the steps are in Authorization, keys and permissions.

Keys the platform issues on its own endpoints come back into service under special rules. A subscription-billed key 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 issuance-check codes 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 re-issued where they were originally issued.

The mode of Cowork/Code keys lives on the seat — the pair of an employee and a Bitrix24 account, shared by all of the employee's devices. So changing mode on a desktop app key does not go through here at all, and on a third-party agent key billed to the subscription it is capped by the seat mode. A request carrying the same mode, sent for a rename, is not a change and goes through.

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.

A separate restriction applies to an authorization key (vibe_app_): a request that changes mode, status or expiresAt does not run at the same time as another operation on a key of the same application.

The codes below apply to any key when the corresponding operation is performed; only REISSUE_IN_PROGRESS is limited to an application authorization key. In particular, revoking an ordinary vibe_api_ key may also return KEY_MANAGES_FOREIGN_SERVER or KEY_OPERATION_IN_PROGRESS.

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 chatbot, 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 chatbots), a details.agents list, and details.bots (up to 10 regular chatbots). For DELETE /v1/bots/:botId, take the numeric bitrixBotId from the matching details.bots item in the 409 response.

A key whose replacement is unfinished cannot be deleted: the answer is 409 KEY_ROTATION_RECOVERY_REQUIRED. The exception is the new key from a 500 rotation response without the strandedSlots field; the steps are in the POST /v1/keys/:id/rotate section below. Deleting an authorization key (vibe_app_) does not run at the same time as another operation on a key of the same application: the answer is 409 REISSUE_IN_PROGRESS. If the key is no longer active or has changed since the request started, the answer is 409 KEY_NOT_ACTIVE.

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.

A blocked key (status: BLOCKED) can be rotated too — it is the only way to replace one; there is no unblocking. The block stays, the old key gets no transition period, and its live access tokens are revoked rather than moved.

A rotation can end with a 500 response — the replacement is then rolled back and the response carries no value for the new key, but the new key has already been created. This happens in three cases:

• KEY_ROTATE_REVOKE_FAILED — for a blocked key, it was not confirmed that its access tokens were revoked.
• KEY_ROTATION_REPOINT_FAILED — the move of bindings to the new key was not confirmed.
• KEY_ROTATION_FINALIZE_FAILED — the completion of the replacement was not confirmed.

The new key's ID arrives in error.details.orphanKeyId. The error.details.strandedSlots field appears when the rollback could not return something to the old key, and lists exactly what. If the field is absent or the list has no previousKeyGrace value, the old key keeps its previous expiry after the rollback. The next steps depend on the strandedSlots field:

• The strandedSlots field is present — contact support. Do not delete the new key while anything still points at it.
• The strandedSlots field is absent — delete the new key with DELETE /v1/keys/:id using the ID from orphanKeyId. After the 204 response, rotate the old key once more. If the deletion returns 409 KEY_ROTATION_RECOVERY_REQUIRED, contact support.

Until the replacement is finished, rotating or deleting either the old or the new key answers 409 KEY_ROTATION_RECOVERY_REQUIRED, so retrying the rotation without these steps does not go through. The exception is deleting the new key as described in the second item above.

If the source key's binding changes during issuance, the answer is 409 KEY_ROTATION_SOURCE_CHANGED. If the key is deleted, the answer is 404 KEY_NOT_FOUND. Neither outcome creates a new key. Re-read the current key record and state before starting a new operation.

Rotation refusals for an unfinished replacement and concurrent operations:

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 subscription-billed key, 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 re-issued where they were originally 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