
## Запросить код для входа с устройства

`POST /v1/connect/device/authorize`

Выдаёт код подтверждения для входа с устройства без браузера: телевизор, приставка, утилита в терминале — там, где ввод логина и пароля затруднён. Пользователь подтверждает вход на телефоне или компьютере, а доступ получает устройство. Поток описан стандартом RFC 8628.

Приложению нужен разрешённый вход с устройства: он включается платформенным администратором и только проверенным приложениям. Клиент, зарегистрированный самостоятельно, получит `400 unauthorized_client` — это защита пользователей от того, чтобы код подтверждения показывало непроверенное приложение.

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

Запрос принимает `application/json` и `application/x-www-form-urlencoded`.

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `client_id` | string | да | Идентификатор приложения, которому платформенный администратор разрешил вход с устройства |
| `scope` | string | нет | Запрашиваемые права через пробел или запятую. Если не передать — применяются права, зарегистрированные для клиента |
| `code_challenge` | string | условно | Хеш SHA-256 от `code_verifier` в `base64url` без `=`. Обязателен, если PKCE включён в настройках клиента. Переданный хеш платформа сохраняет и сверяет с `code_verifier` при опросе |
| `code_challenge_method` | string | условно | `S256`, обязателен вместе с `code_challenge` |
| `device_id` | string | нет | Постоянный идентификатор установки приложения: до 128 символов, латинские буквы, цифры и знаки `.`, `:`, `-`, `_`. Платформа добавляет его в `verification_uri_complete` параметром `device_id`, чтобы связать шаги одного входа, даже если ссылку откроют в другом браузере. Значение другой формы отбрасывается без ошибки: ответ остаётся `200`, ссылка приходит без параметра. На выдачу ключа стороннему приложению не влияет |
| `login_source` | string | нет | Ваша метка кнопки входа для статистики: строчная латинская буква, затем строчные латинские буквы, цифры и `_`, всего до 64 символов. Пробелы по краям обрезаются. Некорректная метка вход не прерывает и на права и выдачу ключа не влияет |

## Примеры

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

Сохраните `code_verifier` до обмена в `POST /v1/connect/token`. В примере curl используется пара из RFC 7636: `code_verifier` равен `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk`. Для каждого входа создавайте новую случайную пару, как в примере JavaScript.

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/connect/device/authorize \
  -H "Content-Type: application/json" \
  -d '{"client_id":"YOUR_CLIENT_ID","scope":"crm","code_challenge":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM","code_challenge_method":"S256"}'
```

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

```javascript
const base64url = bytes => btoa(String.fromCharCode(...bytes))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
const code_verifier = base64url(crypto.getRandomValues(new Uint8Array(32)))
const challenge = base64url(new Uint8Array(
  await crypto.subtle.digest('SHA-256', new TextEncoder().encode(code_verifier)),
))

const res = await fetch('https://vibecode.bitrix24.tech/v1/connect/device/authorize', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'YOUR_CLIENT_ID',
    scope: 'crm',
    code_challenge: challenge,
    code_challenge_method: 'S256',
  }),
})

const data = await res.json()
// data.user_code и data.verification_uri — показать пользователю
// data.device_code — хранить на устройстве, на экран не выводить
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `device_code` | string | Секрет устройства. На экран не выводится, передаётся при опросе `POST /v1/connect/token` |
| `user_code` | string | Код, который показывается пользователю вместе с адресом |
| `verification_uri` | string | Адрес, на котором пользователь вводит код |
| `verification_uri_complete` | string | Тот же адрес с уже подставленным `user_code` |
| `expires_in` | integer | Сколько секунд у пользователя есть на подтверждение |
| `interval` | integer | Интервал опроса `POST /v1/connect/token` в секундах |

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

```json
{
  "device_code": "MYQnuWB3H0tR...",
  "user_code": "54BV-XT8F",
  "verification_uri": "https://vibecode.bitrix24.tech/connect/device",
  "verification_uri_complete": "https://vibecode.bitrix24.tech/connect/device?user_code=54BV-XT8F",
  "expires_in": 899,
  "interval": 5
}
```

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

400 — вход с устройства этому клиенту не разрешён:

```json
{
  "error": "unauthorized_client",
  "error_description": "Client is not enabled for the device flow"
}
```

## Ошибки

Отказы приходят в форме RFC 6749 — `{ error, error_description }`:

| HTTP | `error` | Условие |
|------|---------|---------|
| 400 | `invalid_request` | Не передан `client_id`. `error_description` — `Missing client_id` |
| 401 | `invalid_client` | `client_id` неизвестен либо клиент отключён |
| 400 | `unauthorized_client` | Вход с устройства этому клиенту не разрешён. `error_description` — `Client is not enabled for the device flow` |
| 400 | `unauthorized_client` | Клиент в режиме `COMPANY`. `code` и `error_description` — `CONNECT_COMPANY_DEVICE_FLOW_FORBIDDEN` |
| 400 | `invalid_request` | PKCE обязателен клиенту, а `code_challenge` не передан, либо метод не `S256` или хеш некорректен |
| 400 | `invalid_scope` | Запрошено неизвестное право или право за пределами зарегистрированного набора клиента |

Эндпоинт ограничен по частоте — 30 запросов в минуту по адресу вызывающего, `client_id` в ключ не входит. Сверху действует ограничитель на входе в платформу, общий на весь `/v1/`. Превышение любого из них даёт `429` в общем конверте API с заголовком `Retry-After`. Какой именно сработал, видно по наличию `X-RateLimit-Limit`.

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

## Известные особенности

**Пользователь открывает адрес и подтверждает.** На экране подтверждения он видит карточку приложения, запрошенные права, выбор портала и предупреждение о фишинге: подтверждать следует только тот вход, который начал он сам.

**Устройство опрашивает `/v1/connect/token`.**

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/connect/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "client_id": "YOUR_CLIENT_ID",
    "device_code": "DEVICE_CODE",
    "code_verifier": "CODE_VERIFIER"
  }'
```

Пока пользователь не подтвердил — `400` с одним из состояний:

| `error` | Что делать |
|---------|------------|
| `authorization_pending` | Ждать и опрашивать дальше с интервалом `interval` |
| `slow_down` | Опрос идёт чаще разрешённого. Увеличить интервал на 5 секунд и продолжать |
| `access_denied` | Пользователь отклонил. Прекратить опрос |
| `access_denied` с `error_description=admin_approval_requested` | Пользователь попросил администратора портала разрешить приложению AI. Приходит, когда на платформе включено разрешение AI администратором портала. Прекратить опрос, а после решения администратора запросить новый код через `POST /v1/connect/device/authorize` |
| `expired_token` | Код истёк. Запросить новый через `POST /v1/connect/device/authorize` |
| `invalid_grant` | Пользователь подтвердил вход, но `code_verifier` не передан или не соответствует `code_challenge` из запроса кода. Повторить опрос с верным `code_verifier` |

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

Обрабатывать обе одинаково: ждать не меньше значения `Retry-After` и продолжать опрос, не сбрасывая свою растущую паузу. Отличить их, если нужно, можно по наличию `X-RateLimit-Limit`.

После подтверждения тот же запрос отдаёт `200` с ключом и двумя наборами прав:

```json
{ "api_key": "vibe_api_...", "scopes": ["crm"], "granted_scopes": ["crm"] }
```

Обратите внимание: здесь объект **уже**, чем в основном потоке, — без блоков `portal` и `user`.

Ключ отдаётся **один раз**. Повторный опрос тем же `device_code` вернёт `expired_token`, поэтому сохраняйте ключ сразу.

**Что обязано уметь устройство:**

- **Показывать обратный отсчёт.** Код живёт 15 минут. По истечении показать новый, а не мёртвый экран.
- **Соблюдать `interval` и реагировать на `slow_down`.** Опрос чаще разрешённого не ускорит выдачу, а приведёт к отказам.
- **Читать `Retry-After` и наращивать собственную паузу.** Значение заголовка — минимальная пауза, а не гарантия, что следующий запрос примут: за лимит по адресу конкурируют все запущенные копии приложения. Ждать не меньше `Retry-After` и при этом увеличивать свою паузу с каждым отказом.
- **Не показывать `device_code`.** На экран идёт только `user_code`.

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

- [Обменять код на API-ключ](/docs/partner-connect/token)
- [Публичный клиент: поток с PKCE](/docs/partner-connect/pkce)
- [Partner Connect](/docs/partner-connect)
