Creating and using a key

A key is a credential for accessing the Vibecode API. This page walks through creating a key in the dashboard step by step and covers every form parameter: name, scopes, expiration, rate limit and the allowed IP list.

Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

A scope is a permission to access a particular group of Bitrix24 account data. Which scopes to choose for your task is covered on a separate page: Scopes.

Documentation sections

• Key self-description — what GET /v1/me reveals about the key, Bitrix24 account, plan and available capabilities
• Application user authorization — sign in through Bitrix24 and exchange the code for a session token, for applications acting on behalf of different users
• API reference for the model — GET /v1/guide, the field contract of all entities without a session token
• Access mode — read-only key, Bitrix24 account policy, write blocking

Key types

API key (vibe_api_). Created in the dashboard and bound to a single Bitrix24 account. All requests run on behalf of the key owner — no session token is required. Suitable for personal dashboards, scripts, server integrations and bots on your own Bitrix24 account.

Authorization key (vibe_app_). Bound to a Vibecode application with Bitrix24 OAuth credentials. Every request is sent on behalf of the user who installed the application and completed authorization, so the Authorization: Bearer header is required. Suitable for applications from the catalog that operate on behalf of different users of the Bitrix24 account where the application is registered. This same key is needed for the application to open inside Bitrix24 — in the left menu, a CRM tab or a widget (section Embedding an app in the Bitrix24 account).

Management key (vibe_live_). It is not bound to a single Bitrix24 account and is intended for administration: managing keys, viewing Bitrix24 accounts, working with feedback. It has no access to Bitrix24 entity data. Full description — Management keys.

The rest of this page covers creating both account-level keys: the API key (vibe_api_) and the authorization key (vibe_app_). The two forms differ, and the difference is described below. The management key (vibe_live_) is described separately — Management keys.

Creating an API key

1. Sign in to the dashboard.
2. Open the API Keys section.
3. Click Create Key.
4. Fill in the form (steps below).
5. Copy the key — it is shown once.

Step 1. Name

An arbitrary name for your own reference — it identifies the key in the list. It does not affect access. Create a separate key with a clear name for each service or integration — this makes revocation easier if a key is compromised.

Step 2. Scopes

In the form, scopes are grouped into the "Bitrix24" and "Vibecode" tabs. You must select at least one.

The full list of scopes, a description of each and how to choose a set for your task are on the Scopes page. Quick reference: crm — CRM data, tasks — tasks, imbot + im — chat bot, disk — files.

The Vibecode scopes (vibe:infra, vibe:ai, vibe:search, vibe:storage, vibe:feedback) are pre-selected in the form — a key issued without changes gets them all. The checkboxes are live, though: clear the ones you do not need and the key is issued with exactly what remains. A key holding only vibe:storage returns 403 for server creation and for AI calls.

The set of Bitrix24 scopes is fixed for the key at issue time. If you add a Bitrix24 scope in the settings of an already existing key, GET /v1/me shows it in the list, but requests that need it return BITRIX_ACCESS_DENIED: the key accesses Bitrix24 data with the set of scopes it was issued with. To grant a key a new Bitrix24 scope:

• API key (vibe_api_) — reissue the key or create a new one with the scope selected.
• Authorization key (vibe_app_) — create the application again with the required scope and complete authorization again (reissuing the key does not grant a scope here).

A scope is granted at issue time only if it is available in the Bitrix24 account. If after reissuing or re-authorizing the call still returns BITRIX_ACCESS_DENIED, the scope is not granted to this key in the Bitrix24 account.

Step 3. Expiration

When the key stops working. Options: no expiration, 30, 90, 180 or 365 days. After expiration, requests with the key are rejected with code KEY_EXPIRED. For server integrations, set an expiration date and reissue the key in advance.

Step 4. Rate limit

An optional per-minute limit on the key's calls to AI endpoints. An empty field means the general platform limit for AI calls.

Only a Bitrix24 account administrator can set the value. For everyone else the field is unavailable in the form, and an attempt to pass it through the API is refused with 403 RATE_LIMIT_ADMIN_ONLY.

The field does not affect the other /v1/ endpoints — their rate is bounded by the platform edge and the Bitrix24 account limit, see the "Request limits" section.

Step 5. Allowed IP list

In the "Advanced settings" block. Restricts the key's calls to a list of IP addresses. Exact IPv4 and IPv6 addresses are supported, one per line. CIDR subnets are not supported.

192.168.1.100
203.0.113.42
2001:db8::1

A request from an address outside the list is rejected with code 403 IP_NOT_ALLOWED. If the list is empty, there is no IP restriction.

Step 6. Save the key

The full key is shown once, right after creation. Copy it and save it in a secure place — you cannot retrieve it again, only reissue it.

Creating an authorization key

The authorization key (vibe_app_) is created in the Auth Keys section of the dashboard. The form is shorter than the API key's: just two fields.

1. Open the Auth Keys section and click Create Key.
2. Name — it identifies the application in the list.
3. Scopes — the same two groups "Bitrix24" and "Vibecode", at least one. Choosing a set is described on the Scopes page.
4. Copy the key — it is shown once.

Expiration, rate limit and the allowed IP list are not set in this form — that is how it differs from the API key form. After creation, the authorization key works together with a session token: each request is sent with the X-Api-Key and Authorization: Bearer headers (the "Passing the key" section).

Embedding an app in the Bitrix24 account

If the application must open inside Bitrix24 — as an item in the left menu, a tab in the CRM card or a widget on the desktop — you need an authorization key (vibe_app_). The API key (vibe_api_) does not support embedding into the Bitrix24 account interface: with it the application accesses data but is not placed in the Bitrix24 window.

An authorization key gives two capabilities the API key does not have:

• Placement in the interface. The application appears in the placement you choose in the Bitrix24 account — this is handled by binding a placement. Available placements are returned by the reference, and the full workflow is described in Placements.
• Transparent authorization. The user opens the application inside Bitrix24 without a separate login: the Gateway itself determines who opened the application and passes their data to the application server. The browser does not see the session token.

Steps:

1. Create an authorization key in the Auth Keys section — the form is described above in the "Creating an authorization key" section.
2. Give the AI model the authorization key (vibe_app_) specifically and ask it to build an application that embeds into the Bitrix24 account.
3. The model calls GET /v1/me with this key and gets the placements section with the full embedding sequence.

The full lifecycle of an embedded application, the BFF pattern (Backend-for-Frontend — a separate intermediary server for the frontend) and handler examples in Node, Python and Go — Authorization in a Black Hole application.

Application on your own server

If the application is hosted on your own server, not behind Black Hole, and opens as a placement, the Bitrix24 consent page does not open inside an iframe. You obtain the current user's session token via a one-time code or POST /v1/oauth/placement-session — depending on whose handler receives the placement. The sequence for both cases — Application user authorization.

Passing the key

The key is passed in the X-Api-Key header:

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

Clients that can only send Authorization: Bearer (for example, OpenAI-compatible ones) can pass the API key itself (vibe_api_…) in this header instead of X-Api-Key — for the key both headers are equivalent. This works on all V1 endpoints, including the bot platform:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/bots

For the authorization key (vibe_app_…), the Authorization: Bearer header already carries the session token, so the key itself always goes in X-Api-Key. The single-header Authorization: Bearer method applies only to vibe_api_ and vibe_live_ keys.

For the authorization key (vibe_app_), a session token is additionally passed in the Authorization: Bearer header:

curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/deals

If Authorization: Bearer is not passed for a vibe_app_ key, endpoints that need a user context return 401 TOKEN_MISSING: the request carries no information about which user to act as when calling Bitrix24. The /v1/me, /v1/guide and /v1/oauth/* endpoints work without Bearer.

This also applies to schema endpoints — GET /v1/<entity>/fields and GET /v1/userfields/*: they look like a static schema but request field metadata (including custom fields) from Bitrix24 in real time, so they also require a user context. To discover the available fields before the application is embedded and before a user session exists, use a personal API key (vibe_api_…) — it returns the schema with a single X-Api-Key header, without Bearer. The 401 TOKEN_MISSING response to such a call points to both options.

What to read and how:

The session token lives 24 hours and is not refreshed. POST /v1/oauth/token (and GET /v1/oauth/poll) issue an access_token with expires_in: 86400 — without a refresh_token and without a refresh request. There is no renewal mechanism — this is a deliberate decision. Once the 24 hours are up, get a new session token by going through the OAuth flow again: GET /v1/oauth/authorize → POST /v1/oauth/token. After expiration, calls on behalf of a user return 401 INVALID_SESSION — this is a signal to authorize again.

For background scenarios — schedules, server integrations, scripts without a user at the screen who could re-authorize every 24 hours — use a personal API key (vibe_api_…): it works on behalf of the key owner without a session token, and the only time limit is the key's own expiration (see above). The authorization key (vibe_app_…) is intended for applications where a user is present and completes OAuth.

Infrastructure creation endpoints (POST /v1/infra/servers, and also POST /api/agents and POST /api/managed-bots via the dashboard) require the platform to know exactly who is creating the server — this is needed for plan verification and limit accounting. For vibe_app_ keys this means Authorization: Bearer <session> must be present. Reading (GET /v1/infra/servers, GET /v1/me) does not require a session.

How GET /v1/me responds with and without a session — Key self-description.

How many keys you can create

The number of keys per Bitrix24 account user is limited. By default it is 10 keys. The value is set by the Bitrix24 account administrator in the dashboard, on the "Settings" page → "User Limits" card → "Max keys per user" field, and can be raised up to 100.

This limit includes all of the user's keys in the Bitrix24 account — both API keys (vibe_api_) and authorization keys (vibe_app_) that are created when registering applications. There is no separate limit on applications. Applications consume the same counter as personal keys.

When the limit is reached, creating a new key or application returns 409 KEY_LIMIT_REACHED. Keys in any state except revoked count toward the limit, so an expired key does not free a slot — to free a slot, revoke an unused key.

The quota state arrives together with the refusal, in error.details: limit — how many keys are allowed, used — how many are taken. used also counts application authorization keys and keys the platform issued itself, so it can exceed the number of keys shown in the dashboard: not all of them are listed there. The difference is expected, not lost records.

Key lifecycle

Creation → Active → Reissue / Revocation / Deletion

Key states

Readiness for Bitrix24 calls

status: ACTIVE means the platform accepts the key — not that calls to Bitrix24 can run. A personal key (vibe_api_) reaches Bitrix24 through a webhook, and the key may carry none: for example, the Bitrix24 account was on a free plan when the key was issued. Such a key passes authorization, works with Vibecode's own endpoints — and answers 401 TOKEN_MISSING on every call to Bitrix24.

Readiness is visible in two places:

The reasons and the action for each — Error codes. The general procedure: fix the cause on the Bitrix24 side, then reconnect the key — POST /api/keys/:id/reconnect mints a webhook for the existing key without changing the key string. A new key is only needed where reconnect does not apply: app keys, system-managed keys, and keys with no Bitrix24 scopes.

The /v1/me response is cached for 30 seconds, so read it as GET /v1/me?refresh=tariff right after the fix.

Reissue

Reissue creates a new key and gives the old one a 24-hour transition period — this lets you update the key in applications without downtime:

1. Start the reissue in the dashboard.
2. Get the new key.
3. Update the key in your applications.
4. The old key works for another 24 hours.
5. After the transition period ends, the old key becomes invalid.

Revocation and deletion

Revocation moves the key to the REVOKED state: subsequent requests are rejected with 401 KEY_INACTIVE. If the key has active servers, deletion returns 409 KEY_HAS_ACTIVE_SERVERS: the full server count is in details.activeServerCount, and details.servers carries a list of at most the 10 newest ones. Rebind their controlling key — Server access recovery. You do not need to delete the servers themselves. If an agent, a managed bot, or a regular chat-bot (including a disabled Bot Platform row) is controlled by the key, deletion returns 409 KEY_HAS_LINKED_AGENT: the agent count is in details.linkedAgentCount, the bot count is in details.linkedBotCount (managed + regular chat-bots), and details.bots carries up to 10 blocking regular chat-bots with internal botId and numeric bitrixBotId. Take bitrixBotId directly from the 409 response, then delete the chat-bot through DELETE /v1/bots/:botId or transfer it to another key.

A key named Connect: <app> was issued to a third-party application through Partner Connect — you manage it in the "Connected apps" section of your profile, not here. Revoking it there disables every key you issued to that application for that Bitrix24 account at once; revoking a single row in the key list disables only that row.

If a key is compromised

1. Revoke the key in the dashboard.
2. Create a new key with the same scopes.
3. Update the key in all applications.
4. If the revoked key had servers, rebind their controlling key to the new one — Server access recovery.
5. Check the request log for calls from unknown addresses.
6. Enable the allowed IP list.

Security recommendations

• Store keys in environment variables or a secrets manager, not in code and not in git.
• Do not send keys over messengers or email.
• Assign a key only the necessary scopes — choosing a set is described on the Scopes page.
• Create a separate key for each service and revoke unused ones.
• For server integrations, enable the allowed IP list and set an expiration date.
• Reissue keys on a schedule (for example, every 90 days).

Request limits

Three independent mechanisms bound the rate of calls: the Vibecode platform edge, the Bitrix24 account limit and the endpoints' own limits. The daily API-call quota is counted separately from all of them and is described below.

Vibecode platform edge

The main restriction for /v1/. It is counted per client IP address and shared across every key calling from that address. Some endpoints carry their own, stricter limit at the edge — there that one applies.

The refusal is produced at the platform edge, before the request enters the application, so it carries no X-RateLimit-* headers. Retry-After is the signal to retry on.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 1 second."
  }
}

Bitrix24 account limit

The Bitrix24 account limits the rate of calls (by default 10 requests per second, the limit is shared among all of the account's keys). When exceeded, 502 BITRIX_UNAVAILABLE is returned. The value in effect for the key is returned by GET /v1/me in the rateLimit.requestsPerSecond field.

One call counts as one unit. One POST /v1/batch with 50 operations consumes one unit.

Endpoints' own limits

Some endpoints additionally carry a per-minute limit on the key — it is stricter than the platform edge and protects heavy or irreversible operations. The value in effect and what is left of it arrive in the response headers:

If these headers are absent from the response, the endpoint has no limit of its own — only the platform edge applies.

AI endpoints (/v1/chat/completions, /v1/models, /v1/audio/transcriptions) count two buckets: per key and per user. Their refusal carries Retry-After and an X-RateLimit-Scope header naming the exhausted bucket.

Daily API-call quota

When API-call billing with a free daily allowance is active on the Bitrix24 account, responses carry three headers:

This is a mechanism separate from the rate limits above, and X-RateLimit-Remaining here means what is left of the daily allowance, not what is left of a window. Tell the mechanisms apart by their neighbouring headers: X-RateLimit-Quota and X-RateLimit-Used arrive only with the daily quota, X-RateLimit-Limit and X-RateLimit-Reset only with a window limit.

The absence of these three headers means the account has no call counter. This is not an error and not a sign of a failure.

Recommendations for limits

• Combine requests through POST /v1/batch (up to 50 operations per call).
• Cache data that does not change between calls.
• On 429, wait out the pause from the Retry-After header. If the header is absent, retry with an increasing pause (1 s → 2 s → 4 s).
• Where X-RateLimit-* headers arrive, watch what is left and slow down in advance.

Key error codes

The full code reference — Error codes.

Endpoint reference

See also

• Key self-description
• Application user authorization
• API reference for the model
• Access mode
• Server access recovery
• Connecting a self-hosted Bitrix24
• Scopes
• Management keys
• Error codes