# 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](./scopes.md).

## Documentation sections

- [Key self-description](/docs/keys-auth/me) — what `GET /v1/me` reveals about the key, the Bitrix24 account, the plan and the available capabilities
- [Application user authorization](/docs/keys-auth/oauth) — 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](/docs/keys-auth/guide) — `GET /v1/guide`, the field contract of all entities without a session token
- [Access mode](/docs/keys-auth/access-mode) — read-only key, Bitrix24 account policy, write blocking

## Key types

| Type | Prefix | Purpose | Authorization |
|-----|---------|------------|-------------|
| **API key** | `vibe_api_` | Access to Bitrix24 account data through the Vibecode API | `X-Api-Key` header |
| **Authorization key** | `vibe_app_` | Embedding the application in a Bitrix24 account and Bitrix24 OAuth authorization | `X-Api-Key` + session token |
| **Management key** | `vibe_live_` | Platform administration | `X-Api-Key` header |

**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 (see [Embedding an app in the Bitrix24 account](#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](./management-keys.md).

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](./management-keys.md).

## Creating an API key

1. Sign in to the [dashboard](/dashboard).
2. Open the [API Keys](/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](./scopes.md) page. Quick reference: `crm` — CRM data, `tasks` — tasks, `imbot` + `im` — chatbot, `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 still work, 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 pre-selection applies only to keys you create for yourself: no scopes are added to a key issued to a third-party application through [Partner Connect](/docs/partner-connect) — it carries exactly the ones the user confirmed.

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](#reissue) or create a new one with the scope selected.
- **Authorization key (`vibe_app_`)** — re-create the application 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 `KEY_EXPIRED`. For server integrations, set an expiration date and reissue the key before it expires.

### Step 4. Rate limit

An optional per-minute limit on the key's calls to [AI endpoints](/docs/ai). An empty field means the general platform limit for AI calls applies.

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](#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 `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](/apps) section of the dashboard. The form is shorter than the API key's: just two fields.

1. Open the [Auth Keys](/apps) 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](./scopes.md) 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 (see "Passing the key").

## 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](/docs/apps/placements/bind). Available placements are returned by the [reference](/docs/apps/placements/available), and the full workflow is described in [Placements](/docs/apps/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](/apps) 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 app](./infra/app-runtime.md).

### 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](/docs/keys-auth/oauth#application-on-your-own-server).

## Passing the key

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

```bash
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 this key type, the two headers are equivalent. This works on all V1 endpoints, including the bot platform:

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

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

| What you need | What to authorize with | Where to go |
|---|---|---|
| Static field contract (types, `readonly`, `enum`, `required`, `createOnly`) — before installation, without a session | authorization key via `X-Api-Key` (without `Bearer`) | [`GET /v1/guide`](/docs/keys-auth/guide) → field `data.entities[].fieldsDetailed` |
| Human-readable field labels, live Bitrix24 account fields and custom fields `UF_CRM_*` | session (`Bearer`) on an authorization key or a personal API key (`vibe_api_…`) | `GET /v1/<entity>/fields`, `GET /v1/userfields/*` |

**The session token lives for 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 with no user at the keyboard to 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 (`POST /v1/infra/servers`) requires 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](/docs/keys-auth/me).

## How many keys you can create

The number of keys per Bitrix24 account user is limited. By default it is 100 keys, which is also the highest value the setting accepts. The Bitrix24 account administrator can set another value, from 1 to 100, in the dashboard, on the "Settings" page → "User Limits" card → "Max keys per user" field. If a value is already saved in the account settings, that value applies instead of the default.

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.

There is also a second limit: the platform's per-account key cap. It is counted across all live keys on the Bitrix24 account, not per user. Its value is set by the platform, so a Bitrix24 account administrator cannot raise that cap through "Max keys per user".

When either 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 user-limit 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, and `requested` (when present) — how many new keys the operation needs. If `scope` is absent, the per-user limit on the account was reached: raise it in the account settings if `limit` is below 100, or free up slots by revoking unused keys. If `scope: "portal"` arrives, the platform's per-account key cap was reached: deleting individual keys helps only once the total number of live keys on the account drops below `limit`. `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 a sign of lost records.

## Key lifecycle

```
Creation → Active → Reissue / Revocation / Deletion
```

### Key states

| State | API value | Description |
|-----------|----------------|----------|
| **Active** | `ACTIVE` | The key is ready to use |
| **Expired** | `ACTIVE` | The date in `expiresAt` has passed. `status` stays `ACTIVE` — expiry is determined by the date, and requests are rejected with `401 KEY_EXPIRED` |
| **Revoked** | `REVOKED` | The key is deactivated, requests are rejected |

### 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, if 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 returns
`401 TOKEN_MISSING` on every call to Bitrix24.

Readiness is visible in two places:

| Where | What to read |
|-----|--------------|
| `GET /v1/keys` and `GET /v1/keys/{id}` | the `b24Ready` flag: `true` — a webhook is present, `false` — none, `null` — not applicable to this key (an app key, a management key, or a key with no Bitrix24 scopes) |
| [`GET /v1/me`](/docs/keys-auth/me) | the `b24Credentials` block on a personal key: `ready`, and when `ready: false` — `reason`, `paywallCode`, `upgradeUrl` and a `hint` |

The reasons and the action for each — [Error codes](./errors/auth.md#token_missing-401).
The general procedure: fix the cause on the Bitrix24 side, then **reconnect the key** — on
the ["API Keys"](/keys) page of the dashboard, the "Reconnect" item in the key menu. The key
gets a webhook, and the key string stays the same. 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 API key. The old active key can keep working for no more than 24 hours after reissue and no later than its previous expiration time (`expiresAt`). Reissue does not extend that expiration time or reactivate an expired key. A blocked key (`BLOCKED`) gets no transition period.

1. Start the reissue in the dashboard.
2. Get the new key.
3. Update the key in your applications.
4. The old active key works until the earlier of 24 hours after reissue or its previous expiration time. A blocked key gets no transition period.
5. After the transition period ends, the old key becomes invalid.

#### Application authorization key

The transition period above applies to API keys. Reissuing an application authorization key creates a new OAuth registration; the old key is revoked after the replacement is linked.

When an authorization key is reissued from the application card, the new key belongs to the card owner, even when an administrator starts the reissue. The administrator’s action is recorded in the audit log. The new secret is shown once only to the application owner. When an administrator reissues for another owner, the response contains no secret: the platform attempts to replace it in the application environment and reports the delivery result. If there is no server or delivery fails, the owner must reissue the key themselves for manual installation. The owner’s quota applies: replacing their own key needs no free slot, while replacing another user’s old key does. Personal access to ERP is checked for the new key owner; another person’s permissions are not transferred automatically.

If the owner is inactive on the Bitrix24 account, reissue is refused with `APPLICATION_AUTH_KEY_OWNER_INACTIVE`. Transfer the application to an active employee using the “Transfer” action first, then reissue the key. An administrator can transfer the application to themselves. On transfer, the application’s non-revoked keys belonging to the previous owner immediately move to the new owner, but the authorization key secret stays unchanged until reissue. Reissue it after transfer to revoke previous copies. The platform update itself does not migrate previously issued keys.

### Revocation and deletion

To revoke an API key, open ["API Keys"](/keys) in the dashboard, find the active key you need, and choose **"Deactivate"** from its row's ⋮ menu. Once revocation is saved, the key moves to the `REVOKED` ("Revoked") state.

After revocation is saved, the server handling the request clears the key's cached state and the other servers receive a notification. If that notification is lost, another server may keep accepting the key until its cached state expires; the current cache lifetime (TTL) is about 5 minutes. Once that server refreshes the state, requests with the revoked key are rejected with `401 KEY_INACTIVE`.

**"Delete"** in the same menu is a separate action that deletes the key; **"Deactivate"** is sufficient for revocation. **Reissue** creates a new API key. The old active key can keep working for up to 24 hours after reissue, but no later than its previous expiration time; a blocked key (`BLOCKED`) gets no transition period. To revoke the old active key, choose **"Deactivate"**; the propagation delay described above applies.

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](/docs/infra/server-access-recovery). You do not need to delete the servers themselves. If an agent, a managed bot, or a regular chatbot (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 chatbots), and `details.bots` carries up to 10 blocking regular chatbots with their internal `botId` and numeric `bitrixBotId`. Take `bitrixBotId` from the `409` response itself, and first delete the chatbot 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](/docs/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 the key owner is marked as dismissed

When the employee check of a Bitrix24 account finds that the key owner was dismissed in Bitrix24, their keys in that account return `403 OWNER_BLOCKED`. The key is not revoked and stays `ACTIVE`: as soon as Bitrix24 shows the employee as active again, the key works without reissuing. The refusal covers all of this person's keys in the account — personal keys, keys of their OAuth apps and the keys their apps, agents and bots run on — for every user of the account.

- An integration needs a key issued on behalf of an active employee of the account — issue one and replace the old key.
- An administrator of the account hands the dismissed person's apps, servers, agents and bots over to another employee in the employee's card in the "Users" section.
- If the mark is wrong, correct the employee's status in Bitrix24 — after the next check the key works again. If the key still does not work after the employee is restored in Bitrix24, contact support.

### If a key is compromised

1. Open ["API Keys"](/keys), find the compromised key, and choose **"Deactivate"** from its row's ⋮ menu. Once revocation is saved, the key gets the `REVOKED` state. If the revocation notification is lost, another server may keep accepting the key until its cached state expires (the current TTL is about 5 minutes); after that server refreshes the state, requests are rejected with `401 KEY_INACTIVE`.
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](/docs/infra/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 through messaging apps or email.
- Assign a key only the necessary scopes — choosing a set is described on the [Scopes](./scopes.md) 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 limit 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 — in that case it applies instead.

| Parameter | Value |
|----------|----------|
| Limit | 60 requests per second per client IP address |
| Burst allowance | 100 requests above the limit |
| Response when exceeded | `429` with code `RATE_LIMITED` |
| Pause header | `Retry-After: 1` |

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

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

### Bitrix24 account limit

Bitrix24 limits the call rate at the account level, and all keys on the account share that limit. When a single call is rejected in full with `QUERY_LIMIT_EXCEEDED`, Vibecode returns `429 RATE_LIMITED` with the `Retry-After: 2` header. During auto-pagination the overall response can remain `200` while the same code appears in `meta.pageErrorSample`; for `POST /v1/batch`, inspect the sub-call errors. The `rateLimit.requestsPerSecond` field in `GET /v1/me` contains the reference Bitrix24 limit of 10 requests per second; it is not an individual setting or a measured value currently in effect for a specific key.

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 limit in effect and the amount remaining arrive in the response headers:

| Header | Value |
|-----------|----------|
| `X-RateLimit-Limit` | window limit |
| `X-RateLimit-Remaining` | what is left in the current window |
| `X-RateLimit-Reset` | seconds until the window resets |

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:

| Header | Value |
|-----------|----------|
| `X-RateLimit-Quota` | daily allowance |
| `X-RateLimit-Used` | spent today |
| `X-RateLimit-Remaining` | what is left of the allowance |

`X-RateLimit-Used` and `X-RateLimit-Remaining` count usage by completed hours: calls made in the current hour are counted once that hour ends. So the headers lag behind actual usage by up to 70 minutes. If you need the exact remainder, keep your own count of the calls the headers have not included yet.

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.

## Endpoint reference

| Method | Path | Description |
|-------|------|----------|
| GET | [`/v1/me`](/docs/keys-auth/me) | Key self-description: type, Bitrix24 account, scopes, limits, available capabilities |
| GET | [`/v1/guide`](/docs/keys-auth/guide) | Field contract of all entities and API usage rules |
| GET | [`/v1/oauth/authorize`](/docs/keys-auth/oauth#step-1-send-the-user-to-authorization) | Start application user authorization — redirect to the Bitrix24 sign-in page |
| GET | [`/v1/oauth/callback`](/docs/keys-auth/oauth#what-arrives-at-redirect_uri) | Receive the Bitrix24 response. Called by Bitrix24, not the application |
| POST | [`/v1/oauth/token`](/docs/keys-auth/oauth#step-3-exchange-the-code-for-a-session-token) | Exchange the code for a session token |
| GET | [`/v1/oauth/poll`](/docs/keys-auth/oauth#authorization-without-your-own-redirect_uri) | Retrieve the authorization result without your own `redirect_uri` |
| POST | [`/v1/oauth/placement-session`](/docs/keys-auth/oauth#application-on-your-own-server) | Session token for an application on your own server |
| POST | [`/v1/oauth/revoke`](/docs/keys-auth/oauth#session-token-lifetime-and-revocation) | Revoke the session token |

## Error codes

| HTTP | Code | When returned |
|------|-----|---------------------|
| 401 | `KEY_INACTIVE` | The key is revoked or blocked by the platform |
| 401 | `KEY_EXPIRED` | The key has an expiration date and it has passed |
| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 credentials: for `vibe_app_` no `Authorization: Bearer` was passed, for `vibe_api_` the key carries no portal webhook (the reason arrives in `error.details`, see [Error codes](./errors.md)) |
| 401 | `WRONG_AUTH_SCHEME` | A `vibe_app_` authorization key was passed in the `Authorization: Bearer` header. The app key goes in `X-Api-Key`, while `Authorization: Bearer` carries the session token. A client that only speaks `Bearer` should use a personal `vibe_api_` key |
| 403 | `IP_NOT_ALLOWED` | Request from an address outside the allowed IP list |
| 403 | `OWNER_BLOCKED` | The key owner is blocked or no longer active in the Bitrix24 account — [details](/docs/errors/auth#owner_blocked-403) |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode, and the call performs a write — [Access mode](/docs/keys-auth/access-mode) |

The full code reference — [Error codes](./errors.md).

## See also

- [Key self-description](/docs/keys-auth/me)
- [Application user authorization](/docs/keys-auth/oauth)
- [API reference for the model](/docs/keys-auth/guide)
- [Access mode](/docs/keys-auth/access-mode)
- [Server access recovery](/docs/infra/server-access-recovery)
- [Connecting a self-hosted Bitrix24](/docs/connect-self-hosted-bitrix24)
- [Scopes](/docs/scopes)
- [Management keys](/docs/management-keys)
- [Rights to create keys and apps](/docs/access-rights)
- [Error codes](/docs/errors)