#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 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 catalog applications 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.

Next — creating both Bitrix24 account keys: the API key (vibe_api_) and the authorization key (vibe_app_). The forms differ — 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.
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.

Four platform scopes (vibe:infra, vibe:ai, vibe:search, vibe:storage) are added to the key automatically — you do not need to select them.

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 provided for 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 end date and refresh the key in advance.

#Step 4. Rate limit

An optional per-key limit. If the field is empty, the general platform and Bitrix24 account limits apply (the "Request limits" section below). The value in effect for the key is returned by GET /v1/me in the rateLimit.requestsPerSecond field.

#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 Authorization Keys section of the dashboard. The form is shorter than the API key's: just two fields.

1. Open the Authorization Keys section and click Create.
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 chosen place in the Bitrix24 account — this is handled by binding a placement. Available places 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 Authorization 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) and handler examples in Node, Python and Go — Authorization in a BlackHole application.

#Application on your own server

If the application is hosted on your own server, not behind BlackHole, 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 is occupied by 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. For the "find out available fields before embedding the application and before a user session appears" scenario, 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 for such a call itself hints at both paths.

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. After 24 hours expire, 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 the presence of Authorization: Bearer <session>. 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 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.

#Key lifecycle

Creation → Active → Reissue / Revocation / Deletion

#Key states

#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 or a bot 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, and details.agents carries a list of at most 10 linked agents. Delete the agent or the bot first.

#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 end date.
• Reissue keys on a schedule (for example, every 90 days).

#Request limits

Two independent limit systems apply to each key at the same time: the Vibecode platform limit and the Bitrix24 account limit.

#Vibecode platform limit

When exceeded, 429 Too Many Requests is returned with code RATE_LIMITED.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 245
X-RateLimit-Reset: 25

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

#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, retry the request with an increasing pause (1 s → 2 s → 4 s).
• Rely on the X-RateLimit-* headers to avoid getting rejected.

#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
• Scopes
• Management keys
• Error codes