Для 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.

javascript
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:

Terminal
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.

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