# Создание и использование ключа

Ключ — это учётные данные для доступа к API Вайбкод. Эта страница проводит через создание ключа в личном кабинете шаг за шагом и разбирает каждый параметр формы: название, скоупы, срок действия, лимит запросов и список разрешённых IP.

**Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

Скоуп — это разрешение на доступ к определённой группе данных портала. Какие скоупы выбрать под задачу — на отдельной странице [Скоупы](./scopes.md).

## Разделы документации

- [Самоописание ключа](/docs/keys-auth/me) — что `GET /v1/me` рассказывает о ключе, портале, тарифе и доступных возможностях
- [Авторизация пользователей приложения](/docs/keys-auth/oauth) — вход через Битрикс24 и обмен на токен сессии для приложений от лица разных пользователей
- [Справочник API для модели](/docs/keys-auth/guide) — `GET /v1/guide`, контракт полей всех сущностей без токена сессии
- [Режим доступа](/docs/keys-auth/access-mode) — ключ только на чтение, политика портала, блокировка записи

## Типы ключей

| Тип | Префикс | Назначение | Авторизация |
|-----|---------|------------|-------------|
| **API-ключ** | `vibe_api_` | Доступ к данным портала через API Вайбкод | Заголовок `X-Api-Key` |
| **Ключ авторизации** | `vibe_app_` | Встраивание приложения в портал и OAuth-авторизация Битрикс24 | `X-Api-Key` + токен сессии |
| **Менеджмент-ключ** | `vibe_live_` | Администрирование платформы | Заголовок `X-Api-Key` |

**API-ключ (`vibe_api_`).** Создаётся в личном кабинете и привязан к одному порталу Битрикс24. Все запросы идут от лица владельца ключа, токен сессии не требуется. Подходит для личных сводных панелей, скриптов, серверных интеграций и ботов на своём портале.

**Ключ авторизации (`vibe_app_`).** Привязан к Вайбкод-приложению с OAuth-учётными данными Битрикс24. Каждый запрос отправляется от лица пользователя, установившего приложение и прошедшего авторизацию, — поэтому нужен заголовок `Authorization: Bearer`. Подходит для приложений из каталога, которые работают от лица разных пользователей того портала, где приложение зарегистрировано. Этот же ключ нужен, чтобы приложение открывалось внутри Битрикс24 — в левом меню, вкладке CRM или виджете (раздел [Встраивание приложения в портал](#встраивание-приложения-в-портал)).

**Менеджмент-ключ (`vibe_live_`).** Не привязан к одному порталу, предназначен для администрирования: управления ключами, просмотра порталов, работы с обратной связью. Доступа к данным сущностей Битрикс24 не имеет. Полное описание — [Менеджмент-ключи](./management-keys.md).

Дальше — создание обоих ключей портала: API-ключа (`vibe_api_`) и ключа авторизации (`vibe_app_`). Формы отличаются, отличие описано ниже. Менеджмент-ключ (`vibe_live_`) описан отдельно — [Менеджмент-ключи](./management-keys.md).

## Создание API-ключа

1. Войдите в [личный кабинет](/dashboard).
2. Откройте раздел [Ключи API](/keys).
3. Нажмите **Создать**.
4. Заполните форму (шаги ниже).
5. Скопируйте ключ — он показывается один раз.

### Шаг 1. Название

Произвольное название для самого себя — по нему ключ виден в списке. На доступ не влияет. Заведите отдельный ключ с понятным названием для каждого сервиса или интеграции — это упрощает отзыв при компрометации.

### Шаг 2. Скоупы

В форме скоупы сгруппированы во вкладки «Битрикс24» и «Вайбкод», нужно отметить минимум один.

Полный список скоупов, описание каждого и подбор набора под задачу — на странице [Скоупы](./scopes.md). Короткий ориентир: `crm` — данные CRM, `tasks` — задачи, `imbot` + `im` — чат-бот, `disk` — файлы.

Скоупы Вайбкод (`vibe:infra`, `vibe:ai`, `vibe:search`, `vibe:storage`, `vibe:feedback`) отмечены в форме заранее — ключ, выпущенный без правок, получает их все. Галочки при этом рабочие: снимите ненужные, и ключ выпустится ровно с оставшимися. Ключ только с `vibe:storage` вернёт `403` на создание сервера и на вызовы AI.

Набор скоупов Битрикс24 закрепляется за ключом в момент выпуска. Если добавить скоуп Битрикс24 в настройках уже существующего ключа, `GET /v1/me` покажет его в списке, но запросы, которым он нужен, вернут `BITRIX_ACCESS_DENIED`: к данным Битрикс24 ключ обращается с тем набором скоупов, с которым был выпущен. Чтобы выдать ключу новый скоуп Битрикс24:

- **API-ключ (`vibe_api_`)** — [перевыпустите ключ](#перевыпуск) или создайте новый с отмеченным скоупом.
- **Ключ авторизации (`vibe_app_`)** — создайте приложение заново с нужным скоупом и пройдите авторизацию заново (перевыпуск ключа здесь скоуп не выдаёт).

Скоуп выдаётся при выпуске только если он доступен на портале Битрикс24. Если после перевыпуска или повторной авторизации вызов всё ещё возвращает `BITRIX_ACCESS_DENIED`, значит скоуп для этого ключа на портале не предоставлен.

### Шаг 3. Срок действия

Когда ключ перестанет действовать. Варианты: без ограничения, 30, 90, 180 или 365 дней. После истечения срока запросы с ключом отклоняются с кодом `KEY_EXPIRED`. Для серверных интеграций задавайте конечный срок и обновляйте ключ заранее.

### Шаг 4. Лимит запросов

Необязательный индивидуальный лимит для этого ключа. Если поле пустое — применяются общие лимиты платформы и портала (раздел «Лимиты запросов» ниже). Значение, действующее для ключа, возвращает `GET /v1/me` в поле `rateLimit.requestsPerSecond`.

### Шаг 5. Список разрешённых IP

В блоке «Расширенные настройки». Ограничивает вызовы ключа списком IP-адресов. Поддерживаются точные адреса IPv4 и IPv6, по одному в строке. Подсети в формате CIDR (бесклассовая адресация) не поддерживаются.

```
192.168.1.100
203.0.113.42
2001:db8::1
```

Запрос с адреса вне списка отклоняется с кодом `403 IP_NOT_ALLOWED`. Если список пуст — ограничения по IP нет.

### Шаг 6. Сохраните ключ

Полный ключ показывается **один раз** сразу после создания. Скопируйте и сохраните его в надёжном месте — повторно его получить нельзя, только перевыпустить.

## Создание ключа авторизации

Ключ авторизации (`vibe_app_`) создаётся в разделе [Ключи авторизации](/apps) личного кабинета. Форма короче, чем у API-ключа: всего два поля.

1. Откройте раздел [Ключи авторизации](/apps) и нажмите **Создать**.
2. **Название** — под ним приложение видно в списке.
3. **Скоупы** — те же две группы «Битрикс24» и «Вайбкод», минимум один. Подбор набора описан на странице [Скоупы](./scopes.md).
4. Скопируйте ключ — он показывается один раз.

Срок действия, лимит запросов и список разрешённых IP в этой форме не задаются — этим она и отличается от формы API-ключа. После создания ключ авторизации работает в паре с токеном сессии: каждый запрос отправляется с заголовками `X-Api-Key` и `Authorization: Bearer` (раздел «Передача ключа»).

## Встраивание приложения в портал

Если приложение должно открываться **внутри Битрикс24** — пунктом в левом меню, вкладкой в карточке CRM или виджетом на рабочем столе, — для этого нужен **ключ авторизации** (`vibe_app_`). API-ключ (`vibe_api_`) встраивание в интерфейс портала не поддерживает: с ним приложение обращается к данным, но не размещается в окне Битрикс24.

Ключ авторизации даёт две возможности, которых нет у API-ключа:

- **Размещение в интерфейсе.** Приложение появляется в выбранном месте портала — за это отвечает [привязка места встраивания](/docs/apps/placements/bind). Доступные места возвращает [справочник](/docs/apps/placements/available), полный порядок работы — [Места встраивания](/docs/apps/placements).
- **Прозрачная авторизация.** Пользователь открывает приложение внутри Битрикс24 без отдельного входа: Gateway сам определяет, кто открыл приложение, и передаёт его данные серверу приложения. Браузер токен сессии не видит.

Порядок действий:

1. Создайте ключ авторизации в разделе [Ключи авторизации](/apps) — форма описана выше в разделе «Создание ключа авторизации».
2. Передайте AI-модели именно ключ авторизации (`vibe_app_`) и попросите приложение со встраиванием в портал.
3. Модель вызовет `GET /v1/me` с этим ключом и получит раздел `placements` с полным порядком встраивания.

Полный жизненный цикл встроенного приложения, паттерн BFF — отдельный сервер-посредник для фронтенда и примеры обработчика на Node, Python и Go — [Авторизация в приложении на BlackHole](./infra/app-runtime.md).

### Приложение на своём сервере

Если приложение размещено на собственном сервере, а не за BlackHole, и открывается как размещение, страница согласия Битрикс24 внутри `iframe` не открывается. Токен сессии текущего пользователя получают через одноразовый код или `POST /v1/oauth/placement-session` — по тому, чей обработчик принимает размещение. Порядок для обоих случаев — [Авторизация пользователей приложения](/docs/keys-auth/oauth#приложение-на-своём-сервере).

## Передача ключа

Ключ передаётся в заголовке `X-Api-Key`:

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

Клиенты, которые умеют отправлять только `Authorization: Bearer` (например, OpenAI-совместимые), могут передать сам API-ключ (`vibe_api_…`) в этом заголовке вместо `X-Api-Key` — для ключа оба заголовка равнозначны. Это работает на всех V1-эндпоинтах, включая бот-платформу:

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

У ключа авторизации (`vibe_app_…`) заголовок `Authorization: Bearer` занят токеном сессии, поэтому сам ключ всегда идёт в `X-Api-Key`. Способ с одним заголовком `Authorization: Bearer` применим только к ключам `vibe_api_` и `vibe_live_`.

Для ключа авторизации (`vibe_app_`) дополнительно передаётся токен сессии в заголовке `Authorization: Bearer`:

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

Если для ключа `vibe_app_` не передан `Authorization: Bearer`, эндпоинты, которым нужен пользовательский контекст, возвращают `401 TOKEN_MISSING`: у запроса нет данных, от чьего имени обращаться к Битрикс24. Эндпоинты `/v1/me`, `/v1/guide` и `/v1/oauth/*` работают без `Bearer`.

Это касается и эндпоинтов схемы — `GET /v1/<entity>/fields` и `GET /v1/userfields/*`: они выглядят как статическая схема, но запрашивают метаданные полей (включая пользовательские) у Битрикс24 в реальном времени, поэтому тоже требуют пользовательского контекста. Для сценария «узнать доступные поля до встраивания приложения и появления сессии пользователя» используйте персональный API-ключ (`vibe_api_…`) — он отдаёт схему по одному заголовку `X-Api-Key`, без `Bearer`. Ответ `401 TOKEN_MISSING` для такого вызова сам подсказывает оба пути.

Что каким способом читать:

| Что нужно | Чем авторизоваться | Куда идти |
|---|---|---|
| Статический контракт полей (типы, `readonly`, `enum`, `required`, `createOnly`) — до установки, без сессии | ключ авторизации по `X-Api-Key` (без `Bearer`) | [`GET /v1/guide`](/docs/keys-auth/guide) → поле `data.entities[].fieldsDetailed` |
| Названия полей для отображения, живые поля портала и пользовательские поля `UF_CRM_*` | сессия (`Bearer`) на ключе авторизации или персональный API-ключ (`vibe_api_…`) | `GET /v1/<entity>/fields`, `GET /v1/userfields/*` |

**Токен сессии живёт 24 часа и не обновляется.** `POST /v1/oauth/token` (и `GET /v1/oauth/poll`) выдают `access_token` с `expires_in: 86400` — без `refresh_token` и без запроса на обновление. Механизма продления нет — это сознательное решение. После истечения 24 часов получите новый токен сессии, заново пройдя авторизацию OAuth: `GET /v1/oauth/authorize` → `POST /v1/oauth/token`. После истечения вызовы за пользователя возвращают `401 INVALID_SESSION` — это сигнал заново авторизоваться.

Для фоновых сценариев — расписания, серверные интеграции, скрипты без пользователя у экрана, которому нечем пройти авторизацию заново каждые 24 часа — используйте персональный API-ключ (`vibe_api_…`): он работает от лица владельца ключа без токена сессии, и единственное ограничение по сроку — собственный срок действия ключа (см. выше). Ключ авторизации (`vibe_app_…`) предназначен для приложений, где пользователь присутствует и проходит OAuth.

Эндпоинты создания инфраструктуры (`POST /v1/infra/servers`, а также `POST /api/agents` и `POST /api/managed-bots` через личный кабинет) требуют, чтобы платформа точно знала, **кто** создаёт сервер — это нужно для тарифной проверки и учёта в лимитах. Для ключей `vibe_app_` это значит наличие `Authorization: Bearer <session>`. На чтение (`GET /v1/infra/servers`, `GET /v1/me`) сессия не нужна.

Как `GET /v1/me` отвечает с сессией и без неё — [Самоописание ключа](/docs/keys-auth/me).

## Сколько ключей можно создать

Число ключей на одного пользователя портала ограничено. По умолчанию — 10 ключей. Значение задаёт администратор аккаунта в кабинете, на странице «Настройки» → карточка «Лимиты для пользователей» → поле «Макс. ключей на пользователя», и может поднять его до 100.

В этот лимит входят все ключи пользователя на портале — и API-ключи (`vibe_api_`), и ключи авторизации (`vibe_app_`), которые создаются при регистрации приложений. Отдельного лимита на приложения нет. Приложения расходуют тот же счётчик, что и личные ключи.

Когда лимит достигнут, создание нового ключа или приложения возвращает `409 KEY_LIMIT_REACHED`. В счёт лимита идут ключи в любом состоянии, кроме отозванного, поэтому истёкший ключ место не освобождает — чтобы освободить место, отзовите неиспользуемый ключ.

Состояние квоты приходит вместе с отказом, в `error.details`: `limit` — сколько ключей разрешено, `used` — сколько занято. В `used` входят и ключи авторизации приложений, и ключи, выписанные самой платформой, поэтому число бывает больше, чем список ключей в кабинете: там показаны не все из них. Расхождение ожидаемое, а не потеря записей.

## Жизненный цикл ключа

```
Создание → Активен → Перевыпуск / Отзыв / Удаление
```

### Состояния ключа

| Состояние | Значение в API | Описание |
|-----------|----------------|----------|
| **Активен** | `ACTIVE` | Ключ готов к использованию |
| **Истёк** | `ACTIVE` | Дата в поле `expiresAt` прошла. Поле `status` при этом остаётся `ACTIVE` — истечение определяется по дате, а запросы отклоняются с кодом `401 KEY_EXPIRED` |
| **Отозван** | `REVOKED` | Ключ деактивирован, запросы отклоняются |

### Готовность к вызовам Битрикс24

`status: ACTIVE` означает, что платформа принимает ключ, — но не то, что вызовы к
порталу выполнимы. Личный ключ (`vibe_api_`) ходит в Битрикс24 по вебхуку, и вебхука
на ключе может не быть: например, у портала нет активной подписки на Битрикс24 Маркет
в момент выдачи ключа. Такой ключ проходит авторизацию, работает с эндпоинтами самой
платформы Вайбкод — и отвечает `401 TOKEN_MISSING` на любой вызов к порталу.

Готовность видна двумя способами:

| Где | Что смотреть |
|-----|--------------|
| `GET /v1/keys` и `GET /v1/keys/{id}` | признак `b24Ready`: `true` — вебхук есть, `false` — нет, `null` — к ключу не применимо (ключ приложения, управляющий ключ или ключ без скоупов Битрикс24) |
| [`GET /v1/me`](/docs/keys-auth/me) | блок `b24Credentials` у личного ключа: `ready`, а при `ready: false` — `reason`, `paywallCode`, `upgradeUrl` и подсказка `hint` |

Причины и действия по каждой из них — [Коды ошибок](./errors.md#token_missing-401).
Общий порядок: устранить причину на портале, затем **переподключить ключ** —
`POST /api/keys/:id/reconnect` выдаёт вебхук существующему ключу, не меняя саму строку
ключа. Новый ключ нужен только там, где переподключение не применимо: ключи приложения,
системные ключи и ключи без скоупов Битрикс24.

Ответ `/v1/me` кэшируется на 30 секунд, поэтому сразу после починки читайте его как
`GET /v1/me?refresh=tariff`.

### Перевыпуск

Перевыпуск создаёт новый ключ и оставляет старому переходный период 24 часа — это позволяет обновить ключ в приложениях без простоя:

1. Запустите перевыпуск в личном кабинете.
2. Получите новый ключ.
3. Обновите ключ в своих приложениях.
4. Старый ключ действует ещё 24 часа.
5. По истечении переходного периода старый ключ становится недействительным.

### Отзыв и удаление

Отзыв переводит ключ в состояние `REVOKED`: последующие запросы отклоняются с `401 KEY_INACTIVE`. Если на ключе есть активные серверы, удаление возвращает `409 KEY_HAS_ACTIVE_SERVERS`: полное число серверов — в поле `details.activeServerCount`, а в `details.servers` приходит список не больше чем из 10 самых новых. Смените у них управляющий ключ — [Восстановление доступа к серверу](/docs/infra/server-access-recovery). Удалять сами серверы для этого не нужно. Если ключом управляется агент или бот, удаление возвращает `409 KEY_HAS_LINKED_AGENT`: число агентов — в поле `details.linkedAgentCount`, число ботов — в `details.linkedBotCount`, а в `details.agents` приходит список не больше чем из 10 связанных агентов. Сначала удалите агента или бота.

Ключ с именем `Connect: <приложение>` выдан стороннему приложению через [Partner Connect](/docs/partner-connect) — им управляют не здесь, а в разделе «Подключённые приложения» вашего профиля. Отзыв там гасит сразу все ключи, которые вы выдали этому приложению для этого портала; отзыв одной строки в списке ключей погасит только её.

### Если ключ скомпрометирован

1. Отзовите ключ в личном кабинете.
2. Создайте новый ключ с теми же скоупами.
3. Обновите ключ во всех приложениях.
4. Если на отозванном ключе были серверы, смените у них управляющий ключ на новый — [Восстановление доступа к серверу](/docs/infra/server-access-recovery).
5. Проверьте журнал запросов на обращения с неизвестных адресов.
6. Включите список разрешённых IP.

## Рекомендации по безопасности

- Храните ключи в переменных окружения или менеджере секретов, не в коде и не в git.
- Не передавайте ключи через мессенджеры и почту.
- Назначайте ключу только необходимые скоупы — подбор набора описан на странице [Скоупы](./scopes.md).
- Заводите отдельный ключ для каждого сервиса и отзывайте неиспользуемые.
- Для серверных интеграций включайте список разрешённых IP и конечный срок действия.
- Перевыпускайте ключи по расписанию (например, раз в 90 дней).

## Лимиты запросов

К каждому ключу одновременно применяются две независимые системы лимитов: лимит платформы Вайбкод и лимит портала Битрикс24.

### Лимит платформы Вайбкод

| Параметр | Значение |
|----------|----------|
| Лимит запросов | 300 запросов в минуту на источник |
| Окно лимита | Скользящее окно 60 секунд |
| Заголовок лимита | `X-RateLimit-Limit` |
| Заголовок остатка | `X-RateLimit-Remaining` |
| Заголовок сброса | `X-RateLimit-Reset` (секунды до сброса окна) |

При превышении возвращается `429 Too Many Requests` с кодом `RATE_LIMITED`.

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

### Лимит портала Битрикс24

Портал ограничивает скорость обращений (по умолчанию 10 запросов в секунду, лимит делится между всеми ключами портала). При превышении возвращается `502 BITRIX_UNAVAILABLE`. Действующее для ключа значение возвращает `GET /v1/me` в поле `rateLimit.requestsPerSecond`.

Один вызов считается за единицу. Один `POST /v1/batch` с 50 операциями расходует одну единицу.

### Рекомендации при лимитах

- Объединяйте запросы через `POST /v1/batch` (до 50 операций за вызов).
- Кэшируйте данные, которые не меняются между вызовами.
- При `429` повторяйте запрос с увеличением паузы (1 с → 2 с → 4 с).
- Опирайтесь на заголовки `X-RateLimit-*`, чтобы не доводить до отказа.

### Коды ошибок ключа

| HTTP | Код | Когда возвращается |
|------|-----|---------------------|
| 401 | `KEY_INACTIVE` | Ключ отозван или заблокирован платформой |
| 401 | `KEY_EXPIRED` | У ключа задан срок действия, и он прошёл |
| 401 | `INVALID_API_KEY` | Ключ не найден |
| 401 | `TOKEN_MISSING` | У ключа нет кредов Битрикс24: для `vibe_app_` не передан `Authorization: Bearer`, для `vibe_api_` — на ключе нет вебхука портала (причина в `error.details`, см. [Коды ошибок](./errors.md)) |
| 401 | `WRONG_AUTH_SCHEME` | Ключ авторизации `vibe_app_` передан в заголовке `Authorization: Bearer`. Ключ приложения передаётся в `X-Api-Key`, а `Authorization: Bearer` несёт сессионный токен. Клиенту, который умеет только `Bearer`, подходит личный ключ `vibe_api_` |
| 403 | `IP_NOT_ALLOWED` | Запрос с адреса вне списка разрешённых IP |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | У ключа задан режим «только чтение», а вызов выполняет запись — [Режим доступа](/docs/keys-auth/access-mode) |

Полный справочник кодов — [Коды ошибок](./errors.md).

## Справочник эндпоинтов

| Метод | Путь | Описание |
|-------|------|----------|
| GET | [`/v1/me`](/docs/keys-auth/me) | Самоописание ключа: тип, портал, скоупы, лимиты, доступные возможности |
| GET | [`/v1/guide`](/docs/keys-auth/guide) | Контракт полей всех сущностей и правила работы с API |
| GET, POST | [`/v1/oauth/*`](/docs/keys-auth/oauth) | Авторизация пользователей приложения: вход через Битрикс24, обмен на токен сессии |

## Смотрите также

- [Самоописание ключа](/docs/keys-auth/me)
- [Авторизация пользователей приложения](/docs/keys-auth/oauth)
- [Справочник API для модели](/docs/keys-auth/guide)
- [Режим доступа](/docs/keys-auth/access-mode)
- [Восстановление доступа к серверу](/docs/infra/server-access-recovery)
- [Подключение коробочного Битрикс24](/docs/connect-self-hosted-bitrix24)
- [Скоупы](/docs/scopes)
- [Менеджмент-ключи](/docs/management-keys)
- [Коды ошибок](/docs/errors)