Для AI-агентов: markdown этой страницы — /docs-content/partner-connect/device-authorize.md индекс документации — /llms.txt

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

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-приложение

Terminal
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 Условие
HTTP400 errorinvalid_request УсловиеНе передан client_id. error_description — Missing client_id
HTTP401 errorinvalid_client Условиеclient_id неизвестен либо клиент отключён
HTTP400 errorunauthorized_client УсловиеВход с устройства этому клиенту не разрешён. error_description — Client is not enabled for the device flow
HTTP400 errorunauthorized_client УсловиеКлиент в режиме COMPANY. code и error_description — CONNECT_COMPANY_DEVICE_FLOW_FORBIDDEN
HTTP400 errorinvalid_request УсловиеPKCE обязателен клиенту, а code_challenge не передан, либо метод не S256 или хеш некорректен
HTTP400 errorinvalid_scope УсловиеЗапрошено неизвестное право или право за пределами зарегистрированного набора клиента

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

Полный справочник общих ошибок API — Ошибки.

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

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

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

Terminal
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 Что делать
errorauthorization_pending Что делатьЖдать и опрашивать дальше с интервалом interval
errorslow_down Что делатьОпрос идёт чаще разрешённого. Увеличить интервал на 5 секунд и продолжать
erroraccess_denied Что делатьПользователь отклонил. Прекратить опрос
erroraccess_denied с error_description=admin_approval_requested Что делатьПользователь попросил администратора портала разрешить приложению AI. Приходит, когда на платформе включено разрешение AI администратором портала. Прекратить опрос, а после решения администратора запросить новый код через POST /v1/connect/device/authorize
errorexpired_token Что делатьКод истёк. Запросить новый через POST /v1/connect/device/authorize
errorinvalid_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.

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