
## Обменять код на API-ключ

`POST /v1/connect/token`

Обменивает одноразовый код авторизации на постоянный API-ключ. Принимает `application/json` и `application/x-www-form-urlencoded`.

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `grant_type` | string | да | Для этого потока — `authorization_code`. Без него эндпоинт отвечает `unsupported_grant_type`. Другой режим того же эндпоинта — `urn:ietf:params:oauth:grant-type:device_code` (см. [Вход с устройства без браузера](/docs/partner-connect/device-authorize)). |
| `client_id` | string | да | Идентификатор партнёра |
| `client_secret` | string | условно | Секрет партнёра. Обязателен для конфиденциального клиента, передавать только с серверной стороны. Публичный клиент (`PUBLIC`) его не передаёт |
| `code` | string | да | Код из параметра `code` редиректа |
| `redirect_uri` | string | да | Тот же `redirect_uri`, что был передан в `/v1/connect/authorize` |
| `code_verifier` | string | условно | Исходная строка PKCE. Обязательна, если при авторизации передан `code_challenge`, в том числе для клиента с секретом |

## Примеры

Эндпоинт авторизуется учётными данными приложения — `client_id` и `client_secret` в теле запроса. Заголовки `X-Api-Key` и `Authorization` не нужны.

### curl — OAuth-приложение

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=RECEIVED_CODE \
  -d redirect_uri=https://yourapp.com/callback
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    code: receivedCode,
    redirect_uri: 'https://yourapp.com/callback',
  }),
})

const data = await res.json()
// data.api_key — постоянный API-ключ Вайбкод
// data.portal — выбранный пользователем портал
// data.scopes — запрошенные скоупы, data.granted_scopes — права ключа
// data.user — пользователь, выдавший доступ
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `api_key` | string | API-ключ Вайбкод в формате `vibe_api_...`. Передавать в заголовке `X-Api-Key` при последующих вызовах |
| `portal.domain` | string | Домен портала Битрикс24, например `example.bitrix24.ru` |
| `portal.name` | string | Название портала |
| `scopes` | string[] | Права, запрошенные приложением. На странице согласия пользователь подтверждает набор целиком |
| `granted_scopes` | string[] | Права, которые реально несёт выданный ключ. У самостоятельно зарегистрированного партнёрского приложения как правило, совпадают со `scopes`. Разойдутся, если права ключа изменили после согласия |
| `user.name` | string | Имя пользователя, выдавшего доступ |
| `user.email` | string | Электронная почта пользователя |

Два набора прав расходятся только у приложений, которым состав прав назначает сама платформа — например у настольного приложения [Коворк/Код](/docs/cowork). Такое приложение может не запрашивать ничего, тогда `scopes` приходит пустым, а `granted_scopes` перечисляет весь набор ключа. Проверяйте доступ по `granted_scopes`.

Поле `granted_scopes` может отсутствовать в ответе, если платформа не смогла прочитать права выданного ключа. Пустым оно при этом не приходит, поэтому отсутствие поля означает «набор неизвестен», а не «прав нет» — в таком ответе ориентируйтесь на `scopes`.

Набор в `granted_scopes` отражает то, что записано в ключе. Отдельное право портал Битрикс24 может не подтвердить на своей стороне, поэтому отказ разбирайте по коду ответа Битрикс24, а не по наличию права в списке.

## Пример ответа

```json
{
  "api_key": "vibe_api_...",
  "portal": {
    "domain": "example.bitrix24.ru",
    "name": "Моя компания"
  },
  "scopes": ["crm", "task"],
  "granted_scopes": ["crm", "task"],
  "user": {
    "name": "Иван Иванов",
    "email": "ivan@example.com"
  }
}
```

## Пример ответа при ошибке

400 — не передан обязательный параметр:

```json
{
  "error": "invalid_request",
  "error_description": "Missing client_id, code or redirect_uri"
}
```

## Ошибки

Эндпоинт отвечает в форме RFC 6749 — `{ error, error_description }`, без обёртки `success`. Это сделано ради совместимости с готовыми OAuth-библиотеками. Исключение — отказ ограничителя частоты самого эндпоинта, его форма описана после таблицы.

| HTTP | `error` | Условие |
|------|---------|---------|
| 400 | `invalid_request` | Не передан один из `client_id`, `code`, `redirect_uri` |
| 400 | `invalid_grant` | Код не существует, истёк, уже был использован, либо `redirect_uri` не совпадает с переданным в `/v1/connect/authorize` |
| 400 | `invalid_grant` | Проверка PKCE не прошла: `code_verifier` не передан либо не соответствует переданному ранее `code_challenge`. Код при этом уже израсходован: повтор с верным `code_verifier` тоже вернёт `invalid_grant`, авторизацию начинают заново |
| 400 | `invalid_client` | Публичный клиент прислал `client_secret` — публичному клиенту секрет не выдаётся и передавать его нельзя |
| 400 | `unsupported_grant_type` | `grant_type` не передан или не входит в режимы, перечисленные в поле `grant_type` выше |
| 401 | `invalid_client` | `client_id` неизвестен, клиент отключён, либо `client_secret` не совпадает |
| 403 | `access_denied` | Клиент в режиме `COMPANY`, и в выдаче ключа Компании отказано. `code` и `error_description` несут машинный код причины: `CONNECT_COMPANY_NOT_READY` — технические условия подключения не выполнены, `CONNECT_COMPANY_DISABLED` — подключение недоступно для этого пользователя или портала. Подробнее — [Подключение Компании](/docs/partner-connect/company) |
| 400 | `invalid_request` | Опрос входа с устройства: не передан `client_id` или `device_code`. `error_description` — `Missing client_id or device_code` |
| 401 | `invalid_client` | Опрос входа с устройства: клиент неизвестен, отключён или вход с устройства ему не разрешён |
| 400 | `unauthorized_client` | Опрос входа с устройства от клиента в режиме `COMPANY`. `code` и `error_description` — `CONNECT_COMPANY_DEVICE_FLOW_FORBIDDEN` |
| 429 | `slow_down` | Превышен лимит частоты на входе в платформу. Лимит считается по адресу вызывающего и общий для обмена кода и опроса устройства. Ответ несёт `Retry-After` с минимальной паузой в секундах и не несёт заголовков `X-RateLimit-*` |

**Ограничителей частоты два, и оба отвечают `429`.** Различать их по заголовку `X-RateLimit-Limit`. Отказ на входе в платформу из таблицы выше этого заголовка не несёт и приходит в форме RFC 6749. Отказ самого эндпоинта его несёт, а тело приходит в общем конверте API — `{ "success": false, "error": { "code": "RATE_LIMITED", "message": "..." } }`. Действие в обоих случаях одно: подождать и повторить, увеличив паузу.

Отказы выдачи, переподключения и ротации секрета в режиме `COMPANY` приходят с HTTP 400, 403, 409, 429 и 503 и полем `code`, отказ `429 CONNECT_COMPANY_ATTEMPT_LIMITED` несёт ещё `retryAfterSeconds` — перечень в разделе [Переподключение и ротация секрета](/docs/partner-connect/company#переподключение-и-ротация-секрета).

Полный справочник общих ошибок API — [Ошибки](/docs/errors).

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

- [Начать авторизацию пользователя](/docs/partner-connect/authorize)
- [Публичный клиент: поток с PKCE](/docs/partner-connect/pkce)
- [Вход с устройства без браузера](/docs/partner-connect/device-authorize)
- [Время жизни, отзыв и лимит ключей](/docs/partner-connect/keys)
- [Partner Connect](/docs/partner-connect)
