# Management keys

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

## Difference from Bitrix24 account keys

| Capability | API key (`vibe_api_`) | Authorization key (`vibe_app_`) | Management key (`vibe_live_`) |
|-------------|------------------------|--------------------------------|--------------------------------|
| Bound to a Bitrix24 account | Yes (one Bitrix24 account) | Yes (one Bitrix24 account) | No (all of the user's Bitrix24 accounts) |
| Access to Bitrix24 entities (deals, tasks, etc.) | Yes | Yes | No |
| Managing API keys | No | No | Yes |
| Viewing the Bitrix24 account list | No | No | Yes |
| Working with feedback | Own tickets only | Own tickets only | All platform tickets |
| API reference (`/v1/guide`) | Filtered by scopes | Filtered by scopes | Full (all entities) |

## Management key scopes

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

| Scope | Grants |
|-------|-----------|
| `vibe:mgmt:keys` | `/v1/keys` (list, create, update, delete, rotate) |
| `vibe:mgmt:portals` | `/v1/portals` |
| `vibe:mgmt:feedback` | `/v1/feedback` (ticket list, read, update, comments) |

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.

## Available endpoints

When calling Bitrix24 entity endpoints, `403 MANAGEMENT_KEY_NO_ENTITY_ACCESS` is returned.

### `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.

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

Response:
```json
{
  "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 with a reference of 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.

```bash
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.

```bash
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, with the role in each Bitrix24 account.

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

### `GET /v1/keys` — the Bitrix24 account's API key list

The `portalId` parameter is required.

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

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

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

```bash
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
```

Additional error codes:

| Code | HTTP | When returned |
|-----|------|---------------------|
| `MISSING_PORTAL_ID` | 400 | `portalId` not provided in the request body |
| `NOT_PORTAL_MEMBER` | 403 | The key owner is not a member of the specified portal |
| `PORTAL_NOT_LINKED` | 400 | The portal is not connected to Bitrix24 Network — the key cannot be created |
| `BITRIX_UNAVAILABLE` | 502 | Bitrix24 did not respond to the incoming webhook registration |

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

Returns the key data without the secret (only prefix, name, scopes, status).

```bash
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):

| Field | Type | Description |
|------|-----|----------|
| `name` | string | Key name in the dashboard |
| `scopes` | string[] | List of scopes — see [Scopes](./scopes.md) |
| `status` | `"ACTIVE"` \| `"REVOKED"` | Activate or revoke the key |
| `ipWhitelist` | string[] | List of allowed IP addresses |
| `rateLimit` | number \| null | Custom request limit per second |
| `expiresAt` | ISO-8601 \| null | Key expiration (`null` — never expires) |

```bash
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 or a bot is controlled by the key, deletion returns `409 KEY_HAS_LINKED_AGENT` with the fields `details.linkedAgentCount`, `details.linkedBotCount`, and a `details.agents` list — delete the agent or the bot first.

```bash
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.

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

### `GET /v1/feedback` — feedback ticket list

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

```bash
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

| Status | When applied |
|--------|-------------------|
| `NEW` | The user has just submitted the ticket, no one has looked at it yet |
| `REVIEWING` | The team has started working on the ticket, the user is not yet receiving updates |
| `AWAITING_USER` | The team asked the user a clarifying question — awaiting a reply (the user receives an email) |
| `NEEDS_REVIEW` | The user replied to the clarification — the team reads the new comment and decides the next step |
| `RESOLVED` | The fix is published in the production environment, the user has been notified |
| `ARCHIVED` | Closed without a code change (duplicate, off-topic, not reproducible) |

#### 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 dashboard (the "Management Keys" section)
2. Get the Bitrix24 account list: `GET /v1/portals`
3. View the existing keys in the required 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 obtained 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](./keys-auth.md) — key creation, types, passing, limits, IP, lifecycle, security
- [Scopes](./scopes.md) — scope reference and how to choose them
- [Quickstart](./quickstart.md) — first request in 2 minutes
- [Optimization and batch](./optimization.md) — 50× speedup via `POST /v1/batch`
- [Error codes](./errors.md) — API error reference