Для 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-приложение
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-приложение
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 в секундах |
Пример ответа
{
"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 — вход с устройства этому клиенту не разрешён:
{
"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.
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 с ключом и двумя наборами прав:
{ "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.