## 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/Code 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/Code](/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 issued anew.

The "Get a key" button is absent from the page until Cowork/Code access is granted — the request form lives on the same page. The button is visible but not clickable when the account administrator has disallowed third-party clients, and an explanatory note stands 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 account data is closed to the agent.

**Infrastructure is always unavailable to a subscription key.** Creating servers, deploying, and running commands are closed to any key carrying the Cowork/Code scope — such a request answers `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. A separate key with the deploy scope is issued by the desktop app — [Project key for deploy](/docs/cowork/deploy-key). To a third-party agent key that endpoint answers `403 COWORK_HARNESS_KEY_FORBIDDEN`.

**The Cowork/Code 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 swap is not provided 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 has a platform purpose. If the key's webhook stops working, revoke the key and issue a new one.

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

## 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 travel into 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": "Bitrix24 CoworkCode",
      "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/Code remain in it. The platform sets that set and it changes — read it with a request rather than a list written into the 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 moment in `resetAt`. Absolute quota numbers are not exposed, only shares. The full response — [Cowork/Code subscription summary](/docs/cowork/me); the expanded state with recommendations and the tier catalog — [Cowork/Code 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 moment, 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 holds a quota. It is resumed in the [Cowork/Code](/cowork) section, and the key stays the same.

**Too many requests — `429`, code `rate_limit_exceeded`.** The per-minute request limit was crossed. Wait out the pause from the `Retry-After` header and repeat the request; the limit tier 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/Code 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 a Cowork/Code desktop-class key — a harness 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/Code subscription on this account |
| 402 | `cowork_model_not_allowed` | The model is not allowed for Cowork/Code. 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/Code 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 |
| 404 | `COWORK_NOT_ACTIVATED` | `GET /v1/cowork/me`: no Cowork/Code subscription found for the user and account |
| 429 | `rate_limit_exceeded` | The per-minute request limit was crossed. The pause is in the `Retry-After` header, the tier 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/Code 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 a Cowork/Code desktop-class 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/Code](/docs/cowork)
- [Cowork/Code subscription summary](/docs/cowork/me)
- [Management keys](/docs/management-keys)
- [Errors](/docs/errors)