Аутентификация
X-KA-Access-Key, scoped-модель, коды 401 и 403
Аутентификация
Scoring API использует один заголовок аутентификации:
X-KA-Access-Key: <ваш ключ>Ключ — непрозрачная строка, выданная владельцем платформы Syncra. Сервис сравнивает её с эталоном за постоянное время (защита от timing-атак). Подписей, токенов и времени в запросе нет: канал — HTTPS, ключ — секрет.
Scoped-модель
Каждый ключ привязан к принципалу (имя платформы-интегратора) и набору ручек (scope):
| Scope | Ручки | Типовой потребитель |
|---|---|---|
scoring | /v1/client/score, /v1/client/verdict | Внешние интеграторы скоринга |
checkout | reveal, copy, reserve/route, match-exit | Внутренний платёжный контур |
payments | payment/create, success, overdue, cancel, dispute | Внутренний платёжный контур |
Ключ со scope scoring:
- открывает обе скоринг-ручки —
200; - на любой другой ручке получает
403с сообщениемX-KA-Access-Key is not provisioned for this endpoint (scope ...).
Платформенные ключи без scope-ограничения (внутренний мост Syncra) не затрагиваются scoped-моделью.
Ключ выдаётся на конкретный scope. Если вашему сценарию нужны ручки вне
scoring — запросите расширение у владельца платформы, а не пытайтесь
обойтись 403.
Коды ошибок доступа
| Код | Условие | Тело (в detail обёртки) |
|---|---|---|
401 | заголовок не передан | X-KA-Access-Key header is required |
401 | ключ не существует | unknown X-KA-Access-Key |
403 | ключ валиден, scope чужой | not provisioned for this endpoint (...) |
401 — «кто ты»; 403 — «ты не туда». Различайте их в обработке:
401 обычно означает проблему конфигурации у вас, 403 — ограничение
выданной зоны.
Хранение и вращение
- Храните ключ в secret manager; в коде — только ссылка (env, vault).
- Вращение: владелец платформы записывает новое значение ключа в хранилище секретов платформы; распространение — минуты (автоматическая синхронизация кластера). Старый ключ перестаёт действовать после синхронизации.
- Передача ключа третьим лицам запрещена; один интегратор — один принципал.
Изоляция данных
Принципал ключа изолирует наблюдения: скоринг-история клиентов одного
интегратора (sellPointKey + clientIdKey) не смешивается с данными
других. Передавайте стабильные идентификаторы — от них зависит качество
скоринга.