Для AI-агентов: markdown этой страницы — /docs-content/partner-connect/pkce.md индекс документации — /llms.txt
Публичный клиент: поток с PKCE
Основной поток — GET /v1/connect/authorize и POST /v1/connect/token — описан для конфиденциального клиента: у него есть сервер и client_secret. Если сервера нет и секрет спрятать негде (мобильное приложение, настольная программа, одностраничное веб-приложение), регистрируйте публичный клиент. Секрет ему не выдаётся, подлинность подтверждает механизм PKCE.
От основного потока поток с PKCE отличается тремя шагами, всё остальное совпадает.
Шаг 1. Создайте пару строк
На каждый запуск потока приложение создаёт случайную строку code_verifier и её хеш SHA-256 в base64url без выравнивающих знаков = — code_challenge.
import crypto from 'node:crypto'
const b64url = (buf) => buf.toString('base64url')
const verifier = b64url(crypto.randomBytes(32))
const challenge = b64url(crypto.createHash('sha256').update(verifier).digest())
verifier храните до конца потока, challenge уходит в первый запрос.
Шаг 2. Передайте хеш в `/v1/connect/authorize`
| Параметр | Значение |
|---|---|
Параметрcode_challenge |
ЗначениеХеш из шага 1 |
Параметрcode_challenge_method |
ЗначениеВсегда S256. Другие значения отклоняются |
Для публичного клиента оба параметра обязательны: без них поток завершится редиректом с error=invalid_request.
Шаг 3. Передайте `code_verifier` в `/v1/connect/token`
Вместо client_secret в обмен уходит code_verifier:
curl -X POST https://vibecode.bitrix24.tech/v1/connect/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"code": "RECEIVED_CODE",
"redirect_uri": "http://127.0.0.1:9999/callback",
"code_verifier": "CODE_VERIFIER"
}'
Ответ тот же, что у конфиденциального клиента, — поля описаны на странице POST /v1/connect/token.
client_secret публичному клиенту передавать нельзя — платформа ответит 400 invalid_client. Секрет, зашитый в раздаваемое приложение, секретом не является, поэтому поток построен так, чтобы им нельзя было воспользоваться.
Возврат на localhost
У программы без своего сайта нет публичного адреса, куда вернуть код. Для таких случаев разрешён возврат на себя: зарегистрируйте redirect_uri вида http://127.0.0.1:9999/callback, на время потока запустите слушатель на этом порту и закройте его сразу после получения кода.
Подходят адреса 127.0.0.1, localhost и [::1], для них разрешены схемы http и https. Все остальные адреса обязаны быть https. Схема и путь сверяются всегда, а порт и сам адрес localhost — в зависимости от типа клиента:
| Тип клиента | Как сверяется адрес на localhost |
|---|---|
| Тип клиентаПубличный | Как сверяется адрес на localhostПорт не учитывается: если он занят, приложение может слушать любой другой, повторно регистрировать адрес не нужно. Адреса 127.0.0.1, localhost и [::1] взаимозаменяемы: зарегистрированный http://127.0.0.1/callback принимает и http://localhost:5123/callback |
| Тип клиентаКонфиденциальный | Как сверяется адрес на localhostАдрес сверяется целиком, включая порт. Так серверное приложение отлаживают на своём компьютере: зарегистрируйте адрес с портом, на котором слушает сервер, например http://localhost:3030/callback |
Имя localhost может указывать не на этот компьютер, если его переопределили в настройках сети, поэтому надёжнее 127.0.0.1.