# Management keys

Management keys (`vibe_live_`) are not tied to a single Bitrix24 account and are intended for automating administration: viewing your Bitrix24 accounts and managing your API keys on them. A management key is created in your Vibecode account, in the Management Keys section.

**Scopes:** `vibe:mgmt:keys`, `vibe:mgmt:portals`, `vibe:mgmt:feedback` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

## Difference from Bitrix24 account keys

| Capability | API key (`vibe_api_`) | Authorization key (`vibe_app_`) | Management key (`vibe_live_`) |
|-------------|------------------------|--------------------------------|--------------------------------|
| Bound to a Bitrix24 account | Yes (a single account) | Yes (a single account) | No (all of the owner's accounts) |
| Access to Bitrix24 entities (deals, tasks, etc.) | Yes | Yes | No |
| Managing your own API keys | No | No | Yes |
| Viewing the list of your Bitrix24 accounts | No | No | Yes |
| Feedback tickets | Own tickets. With the `vibe:feedback` scope, all tickets of its Bitrix24 account | Own tickets. With the `vibe:feedback` scope, all tickets of its Bitrix24 account | Tickets of all Bitrix24 accounts. Only with the `vibe:mgmt:feedback` scope |

## Management key scopes

Each management key is created with one or more scopes. Without the required scope, the endpoint returns `403 MANAGEMENT_SCOPE_REQUIRED`.

| Scope | Grants | Who can grant it |
|-------|-----------|------------------|
| `vibe:mgmt:keys` | `/v1/keys` — list, create, update, delete and rotate your own keys | Any user |
| `vibe:mgmt:portals` | `/v1/portals` — list your Bitrix24 accounts | Any user |
| `vibe:mgmt:feedback` | `/v1/feedback` — tickets of all Bitrix24 accounts on the platform | Vibecode platform administrator only |

Keys with the `vibe:mgmt:keys` and `vibe:mgmt:portals` scopes see only the owner's resources: their Bitrix24 accounts and their keys on them.

The `vibe:mgmt:feedback` scope grants access to tickets of all Bitrix24 accounts, so it is granted only to a platform administrator. A regular user's request to create a key with this scope receives `403 PLATFORM_ADMIN_SCOPE_REQUIRED`. A key whose owner is no longer a platform administrator receives `403 FEEDBACK_PLATFORM_ADMIN_REQUIRED` on `/v1/feedback`.

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

## Owner account state

A management key acts on behalf of its owner, so the state of the owner's account is checked on **every** endpoint — on reads and on writes alike. This check runs before the scope check, so `OWNER_DELETED`, `OWNER_BLOCKED` and `ACCOUNT_PENDING_ERASURE` arrive even where the key lacks the required scope.

| HTTP | Code | When returned |
|------|-----|---------------------|
| 403 | `OWNER_DELETED` | The key owner's account has been deleted |
| 403 | `OWNER_BLOCKED` | The key owner's account has been blocked |
| 503 | `ACCOUNT_PENDING_ERASURE` | The owner requested erasure of their data — the key is frozen until the cancellation window ends. The response carries a `Retry-After: 3600` header. Cancelling the request restores the key; no rotation is needed |
| 409 | `B24_USER_DELETED` | The key owner is no longer an active employee of the target Bitrix24 account — no key can be issued for them. Checked on issuance (`POST /v1/keys`) and rotation (`POST /v1/keys/:id/rotate`), the operations that give a new key an owner. Different from `NOT_PORTAL_MEMBER`: that one arrives when the owner is not a member of the account at all, this one when the record exists but the employee has been deleted or deactivated |

The freeze covers all operations, including issuing, rotating and deleting API keys.

## Management key self-description

[`GET /v1/me`](/docs/keys-auth/me) with a management key responds with `data.type: "management"` and carries no Bitrix24 account data. Instead, the response contains management-specific blocks:

| Field | Description |
|------|----------|
| `data.scopes` | Scopes of the management key |
| `data.portals[]` | The owner's Bitrix24 accounts: `id`, `domain`, `status`, `role` and `appKeyCount` — the number of the owner's keys on the account |
| `data.totalAppKeys` | Sum of `appKeyCount` across all accounts |
| `data.capabilities` | `endpoints` — endpoints available to the management key, `scopesRequired` — which scope grants which path, `reference` — a link to this page |
| `data.quickstart` | Four steps from the account list to working with the created API key |
| `data.feedback` | Reference of feedback ticket endpoints, statuses, categories and filters. The key can use them only with the `vibe:mgmt:feedback` scope |
| `data.docs` | A link to this page |

## Typical workflow

1. Get your Bitrix24 accounts and their IDs: [`GET /v1/portals`](/docs/management-keys/portals).
2. View your keys on the required account: [`GET /v1/keys?portalId=<id>`](/docs/management-keys/list).
3. Create an API key with the required scopes: [`POST /v1/keys`](/docs/management-keys/create). The key value is returned in the response only once.
4. Work with Bitrix24 data using the obtained API key (`vibe_api_…`).

## Limitations

- A management key cannot access Bitrix24 entity endpoints (`/v1/deals`, `/v1/tasks` and others): such a request receives `403 MANAGEMENT_KEY_NO_ENTITY_ACCESS`. Working with data requires an API key (`vibe_api_`) or an authorization key (`vibe_app_`).
- The `/v1/keys` and `/v1/portals` endpoints accept only a management key. A Bitrix24 account key receives `401 WRONG_KEY_TYPE` on them.

## Endpoint reference

| Method | Path | Description |
|-------|------|----------|
| GET | [`/v1/portals`](/docs/management-keys/portals) | List of the owner's Bitrix24 accounts |
| GET | [`/v1/keys`](/docs/management-keys/list) | List of the owner's API keys on a Bitrix24 account |
| POST | [`/v1/keys`](/docs/management-keys/create) | Create an API key |
| GET | [`/v1/keys/:id`](/docs/management-keys/get) | Get an API key |
| PATCH | [`/v1/keys/:id`](/docs/management-keys/update) | Update an API key |
| DELETE | [`/v1/keys/:id`](/docs/management-keys/delete) | Delete an API key |
| POST | [`/v1/keys/:id/rotate`](/docs/management-keys/rotate) | Rotate an API key |
| GET | [`/v1/me`](/docs/keys-auth/me) | Key self-description |
| GET | [`/v1/guide`](/docs/keys-auth/guide) | API reference for the model |
| GET | [`/v1/openapi.json`](/docs/cli#openapi-specification) | OpenAPI specification |
| GET | [`/v1/feedback`](/docs/feedback/list) | List of tickets of all Bitrix24 accounts. Only with the `vibe:mgmt:feedback` scope |
| GET | [`/v1/feedback/:id`](/docs/feedback/get) | Get a ticket. Only with the `vibe:mgmt:feedback` scope |
| PATCH | [`/v1/feedback/:id`](/docs/feedback/update) | Change a ticket status. Only with the `vibe:mgmt:feedback` scope |
| POST | [`/v1/feedback/:id/comments`](/docs/feedback/comments) | Reply to a ticket. Only with the `vibe:mgmt:feedback` scope |

## See also

- [Keys and authorization](/docs/keys-auth)
- [Permissions to create keys and applications](/docs/access-rights)
- [Scopes](/docs/scopes)
- [Error codes](/docs/errors)
- [Recovering access to a bot](/docs/bots/ownership-recovery)