## Your own agent on the subscription

A third-party agent client — OpenCode, Crush, Cline, Aider, or your own code — works with the models through a Cowork subscription key. Requests made with that key draw on the subscription quota rather than the account wallet.

**Scope:** `vibe:ai` + `vibe:cowork` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key` or `Authorization: Bearer`

Such a key has no separate address and no separate protocol: it is the same OpenAI-compatible [AI Router](/docs/ai), only the billing changes. Everything described in the AI section works here as well.

## How to get the key

1. Open the [Cowork](/cowork) section in your Vibecode account.
2. Click "Get a key" — the key creation dialog opens with billing already switched to the subscription.
3. Select the scopes you need and create the key.
4. Copy the key value immediately. It is shown once and cannot be recovered: a lost key is revoked and reissued.

The "Get a key" button does not appear on the page until Cowork access is granted — you request access on the same page. The button is visible but not clickable when the account administrator has disallowed third-party clients, and an explanatory note appears next to it.

## What this key can and cannot do

**By default the key carries every Bitrix24 account scope.** The dialog opens with the data scopes checked, and an agent holding such a key reads and changes account data on your behalf. A single "Clear all" button in the Bitrix24 scope group removes them: the key is then left with the AI scope only, and the agent has no access to account data.

**Infrastructure is always unavailable to a subscription key.** Creating servers, deploying, and running commands are closed to any key carrying the Cowork scope — such a request is refused with `403 INFRA_FORBIDDEN_FOR_COWORK_KEY`. The cleared "Infrastructure" checkbox in the dialog reflects that rather than causing it: checking it again does not grant infrastructure access. A separate key with the deploy scope is issued by the desktop app — [Project key for deploy](/docs/cowork/deploy-key). For a third-party agent key, that endpoint returns `403 COWORK_HARNESS_KEY_FORBIDDEN`.

**The Cowork scope cannot be removed from an issued key.** The key either stays on the subscription or is revoked outright. It cannot be moved to the account wallet, and the reverse switch is not supported either: a wallet-billed key is created separately, in the "API Keys" section.

**The "Reconnect" menu item does not appear for such a key.** That item is meant for keys the platform does not manage itself, and a subscription key is one the platform manages. If the key's webhook stops working, revoke the key and issue a new one.

**Rotation runs the same Cowork checks as issuance.** Rotating a subscription key requires Cowork access to be granted, the account policy to allow third-party clients, and the Cowork subscription to be active. The refusal codes are on the [Rotate an API key](/docs/management-keys/rotate) page.

**The key mode is never wider than the Cowork seat mode.** The seat is the pair of you and the Bitrix24 account, and its access mode is shared by the desktop app and third-party agent keys. Issuance and rotation give a key no wider than the seat mode: a request for a wider mode gets a key in the seat mode. The mode of an issued key cannot be raised above the seat — `PATCH /v1/keys/:id` answers `403 COWORK_KEY_MODE_ABOVE_SEAT`. Widen the seat itself first: its mode is changed by editing the desktop app key in the "API Keys" section of your Vibecode account, and the change applies to all devices at once. Within the seat, the mode changes the same way as on any other key.

## Connecting

Every client is configured the same way: base address `https://vibecode.bitrix24.com/v1`, the key in the `Authorization: Bearer` or `X-Api-Key` header, request and response format OpenAI-compatible. Ready-made configuration fragments follow — the dialog shows the same ones right after the key is created.

The key is not written into the configuration: the `opencode.json` and `.crush.json` files sit next to the code and end up in the repository, so both clients read the value from an environment variable.

### OpenCode

File `opencode.json`.

```bash
# Put the key into an environment variable first
export VIBECODE_API_KEY=<your key>
```

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "bitrix24": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Alaio Cowork",
      "options": {
        "baseURL": "https://vibecode.bitrix24.com/v1",
        "apiKey": "{env:VIBECODE_API_KEY}"
      },
      "models": {
        "bitrix/bitrixgpt-5.5": { "name": "BitrixGPT" }
      }
    }
  }
}
```

### Crush

File `.crush.json`.

```bash
# Put the key into an environment variable first
export VIBECODE_API_KEY=<your key>
```

```json
{
  "providers": {
    "bitrix24": {
      "type": "openai-compat",
      "base_url": "https://vibecode.bitrix24.com/v1",
      "api_key": "$VIBECODE_API_KEY",
      "models": [
        { "id": "bitrix/bitrixgpt-5.5", "name": "BitrixGPT", "context_window": 128000, "default_max_tokens": 8000 }
      ]
    }
  }
}
```

### Cline

Extension settings. Cline keeps the key in the editor's secret storage and has no configuration file next to the code, so the value goes straight into the form.

```
API Provider: OpenAI Compatible
Base URL: https://vibecode.bitrix24.com/v1
API Key: <your key> (same value as in $VIBECODE_API_KEY)
Model ID: bitrix/bitrixgpt-5.5
```

### Aider

Environment variables.

```bash
export OPENAI_API_BASE=https://vibecode.bitrix24.com/v1
export OPENAI_API_KEY=$VIBECODE_API_KEY
aider --model openai/bitrix/bitrixgpt-5.5
```

### curl

Checking the key with a single request.

```bash
# Put the key into an environment variable first
export VIBECODE_API_KEY=<your key>

curl -X POST https://vibecode.bitrix24.com/v1/chat/completions \
  -H "Authorization: Bearer $VIBECODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"bitrix/bitrixgpt-5.5","messages":[{"role":"user","content":"ping"}]}'
```

## Model list

The identifiers for the `model` field are returned by `GET /v1/models`. A subscription key receives that list already narrowed: only the models allowed for Cowork remain in it. The platform defines that list and it changes — read it with a request rather than from a list written into your configuration once.

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

Response fields and the data of a single model — [Models](/docs/ai/models).

## Limits and usage

The subscription tier and the usage of the three quota windows as a percentage are returned by `GET /v1/cowork/me` — with the same key, no extra scopes needed.

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

```json
{
  "tier": "FREE",
  "state": "ACTIVE",
  "quotaPct": { "fiveHour": 40, "week": 24, "month": 20 },
  "resetAt": {
    "fiveHour": "2026-08-22T17:30:00.000Z",
    "week": "2026-08-25T09:00:00.000Z",
    "month": "2026-09-01T00:00:00.000Z"
  },
  "nextChargeAt": null
}
```

The windows are nested and counted simultaneously — 5 hours, a week, and a month. Work stops when any of them is exhausted, and each window has its own reset time in `resetAt`. Absolute quota numbers are not exposed, only percentages. The full response — [Cowork subscription summary](/docs/cowork/me); the expanded state with recommendations and the tier catalog — [Cowork subscription state](/docs/cowork/state).

## What the errors mean

A third-party client has no interface of its own — it shows the `message` field from the response verbatim. The refusal body of the AI endpoints follows the OpenAI format, `{ "error": { "message", "type", "code" } }`, and `code` there is lowercase. The `/v1/cowork/*` responses follow the common platform format, `{ "success": false, "error": { "code", "message" } }`, and `code` there is uppercase.

**The quota window ran out — `402`, code `cowork_quota_exhausted`.** The `window` field names the exhausted window (`5h`, `week`, or `month`), `resetAt` gives the reset time, and `nextTier` the next tier. The `Retry-After` header gives the pause in seconds until the reset. Both waiting for the reset and moving to a higher tier lift the block.

```json
{
  "error": {
    "message": "Cowork/Code quota exhausted for the 5h window. Wait until 2026-08-22T17:30:00.000Z or upgrade your tier.",
    "type": "insufficient_quota",
    "code": "cowork_quota_exhausted",
    "window": "5h",
    "resetAt": "2026-08-22T17:30:00.000Z",
    "nextTier": "PRO"
  }
}
```

**The subscription is not active — `402`, code `cowork_subscription_inactive`.** The key owner's subscription is paused or cancelled and no longer has a quota. It is resumed in the [Cowork](/cowork) section, and the key stays the same.

**The agent answers in a loop — `409`, code `agent_turn_loop_detected`.** After the user's last message, the request holds 20 or more model answers without tool calls: the agent keeps the turn going on its own but does nothing. The request is not sent to the model, and no quota is used. Stop the turn and wait for a message from the user — a new message with the `user` role starts the count over.

**Too many requests — `429`, code `rate_limit_exceeded`.** The per-minute request limit was exceeded. Wait out the pause from the `Retry-After` header and retry the request. The limit scope is named in the `scope` field and in the `X-RateLimit-Scope` header. The other `429` responses of this endpoint are covered by [Request limits and retries](/docs/ai/chat/rate-limits).

**The Cowork interface is switched off on the platform — `503`, code `COWORK_FEATURE_DISABLED`.** This refusal applies to product operations guarded by the switch, such as `GET /v1/cowork/me`. An already-issued key continues to call `POST /v1/chat/completions` through the subscription, with the usual activity, model, and quota checks. The emergency `DELETE /v1/cowork/key` also remains available, but only to the Cowork desktop app key — a third-party agent key cannot call it.

Unless the description names another endpoint, the refusal comes from `POST /v1/chat/completions`.

| HTTP | Code | Description |
|------|-----|----------|
| 402 | `cowork_quota_exhausted` | One of the subscription quota windows is exhausted. The body carries `window`, `resetAt`, and `nextTier`; the `Retry-After` header carries the seconds until the reset |
| 402 | `cowork_subscription_inactive` | The key owner has no active Cowork subscription on this account |
| 402 | `cowork_model_not_allowed` | The model is not allowed for Cowork. The `allowedModelIds` field lists the allowed ones |
| 403 | `scope_missing` | The key lacks the `vibe:ai` scope |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | A request to infrastructure, for example `POST /v1/infra/servers`. Infrastructure is closed to a key carrying the Cowork scope |
| 403 | `COWORK_HARNESS_KEY_FORBIDDEN` | `POST /v1/cowork/deploy-key`: a project key with the deploy scope is not issued to a third-party agent key |
| 403 | `COWORK_KEY_MODE_ABOVE_SEAT` | `PATCH /v1/keys/:id`: the requested key mode is wider than the Cowork seat mode. Widen the seat first |
| 404 | `COWORK_NOT_ACTIVATED` | `GET /v1/cowork/me`: no Cowork subscription found for the user and account |
| 409 | `agent_turn_loop_detected` | 20 or more model answers without `tool_calls` have accumulated after the last message with the `user` role. The request is not sent to the model, and no quota is used |
| 429 | `rate_limit_exceeded` | The per-minute request limit was exceeded. The pause is in the `Retry-After` header, the scope in `X-RateLimit-Scope` |
| 503 | `COWORK_FEATURE_DISABLED` | A product operation guarded by the switch, such as `GET /v1/cowork/me`, is unavailable while Cowork is disabled at the platform level. The switch does not affect `POST /v1/chat/completions`; the emergency `DELETE /v1/cowork/key` is also not gated, but requires the Cowork desktop app key |

The full list of common API errors — [Errors](/docs/errors).

## See also

- [AI Router](/docs/ai)
- [Create a chat completion](/docs/ai/chat/completions)
- [Models](/docs/ai/models)
- [Cowork](/docs/cowork)
- [Cowork subscription summary](/docs/cowork/me)
- [Management keys](/docs/management-keys)
- [Errors](/docs/errors)