For the complete documentation index, see llms.txt. This page is also available as Markdown.

Request Signing

Request Signing проверяет API-запросы с помощью API-секрета. Ключ идентифицирует ваш доступ, а секрет создаёт подпись и никогда не должен передаваться в запросах.

Address Label API и Risk Score API используют отдельные ключи и секреты. Используйте учётные данные вызываемого сервиса.

Включение Request Signing

Полные процедуры настройки, ротации и отключения см. в API Security Settings.

  1. Откройте Settings → APIs → API Keys, затем Security Settings нужного API.

  2. Выберите Request Signing и создайте API-секрет. Скопируйте и безопасно сохраните его: он отображается только один раз.

  3. Выберите, когда подписанные запросы станут обязательными, затем Save Changes:

    • In 24 hours: используйте переходный период для обновления и тестирования приложений. Новый секрет работает после сохранения; до указанного времени запросы без подписи принимаются с учётом других правил доступа.

    • Immediately: после сохранения каждый запрос должен иметь действительную подпись. Убедитесь, что приложения готовы.

  4. Отправляйте подписанные запросы по инструкциям ниже. Обновите все приложения до времени, указанного в Security Settings.

Недействительная подпись отклоняется даже в переходный период. Если включён и IP Allowlist, IP источника должен быть разрешён, а подпись — действительна. Тесты используют реальные рабочие запросы и могут расходовать квоту; отдельного тестового секрета или эндпоинта проверки подписи нет.

Заголовки запроса

Заголовок
Значение

Api-Key

API-ключ соответствующего сервиса

X-Timestamp

Текущая метка времени Unix в секундах

X-Nonce

Новое случайное уникальное значение для каждого запроса, не более 256 байт

X-Signature

v1=, затем подпись HMAC-SHA256 в шестнадцатеричном виде строчными буквами

Метка времени должна отличаться от времени сервера не более чем на 5 минут. Синхронизируйте часы. При каждом повторе создавайте новые метку времени, nonce и подпись.

Используйте API-ключ и секрет только в серверном коде. Загружайте их из переменных окружения или менеджера секретов; никогда не коммитьте их и не включайте в сборки браузерных или мобильных приложений.

Используйте HTTPS с проверкой сертификатов. Request Signing аутентифицирует запросы, но не шифрует содержимое. Не помещайте учётные данные в URL или параметры запроса. Маскируйте ключи, секреты, заголовки подписи и чувствительные данные запросов/ответов в журналах, трассировках, снимках экрана и вложениях для поддержки.

Создание канонической строки

Соедините следующие шесть полей одним символом новой строки (\n). Не добавляйте завершающий перевод строки.

  • METHOD: HTTP-метод в верхнем регистре, например GET или POST.

  • PATH: полный путь URL с префиксом сервиса, без схемы, хоста и строки запроса. Например, /address-compliance/api/v3/risk-score. Использование только /risk-score приведёт к ошибке проверки.

  • SORTED_QUERY_STRING: строка запроса, нормализованная по правилам ниже. При отсутствии параметров используйте пустую строку.

  • BODY_SHA256: хеш SHA-256 точных байтов отправляемого тела в шестнадцатеричном виде строчными буквами. Для пустого тела хешируйте пустую последовательность байтов.

  • TIMESTAMP и NONCE: те же значения, что отправлены в заголовках.

Сериализуйте тело один раз, хешируйте эти байты и отправляйте их без изменений. Изменение пробелов JSON после подписи делает её недействительной.

Нормализация параметров запроса

  1. Разделите исходную строку по &, затем каждую пару по первому =. Отсутствующее значение считайте пустой строкой.

  2. Декодируйте ключи и значения.

  3. Сортируйте по декодированному ключу, затем значению в порядке байтов UTF-8. Сохраняйте повторяющиеся ключи.

  4. Примените процентное кодирование RFC 3986 к каждому ключу и значению. Не экранируйте только A–Z, a–z, 0–9, -, _, . и ~. Пробел кодируйте как %20, буквальный плюс — как %2B.

  5. Соедините пары key=value через &, без начального ?.

Пример:

Используйте UTF-8. Избегайте исходного + в значениях; используйте %20 для пробелов и %2B для плюса. flag и flag= нормализуются в flag=.

Вычисление подписи

Используйте байты UTF-8 отображаемого значения секрета. Не декодируйте его как hex или Base64.

Пример Python

Пример вызывает эндпоинт поддерживаемых цепей Risk Score API. Задайте MS_API_KEY и MS_API_SECRET своими данными Risk Score. Используется HTTPS-эндпоинт рабочей среды. Для разрешённых тестовых сред используйте отдельные данные; не отправляйте рабочие учётные данные недоверенным хостам.

Для JSON POST сериализуйте данные в байты UTF-8, используйте их для хеша тела, затем передайте те же байты в Request как data=body. Установите Content-Type: application/json.

Параметры запросов см. в APIs.

Пример Node.js

Требуется Node.js 18 или новее. Используйте те же переменные Risk Score, что в примере Python. Подписываются точные байты UTF-8, которые отправляются.

Оба примера отклоняют перенаправления. Не пересылайте учётные данные и заголовки подписи на адрес перенаправления. Проверьте ожидаемые HTTPS-хост и путь перед созданием и подписанием нового запроса. HTTP-статус сам по себе не означает успех операции; проверяйте бизнес-код JSON согласно разделу Формат ответа.

Устранение неполадок

Код
Сообщение
Что проверить

401001

Request signing is not configured

Настройте подпись и убедитесь, что для этого API-сервиса доступен секрет.

401002

Invalid request signature

Проверьте данные сервиса, полноту заголовков, полный путь, метод, нормализованный запрос, точные байты тела и длину nonce (до 256 байт).

401003

Invalid request timestamp

Используйте секунды Unix и синхронизируйте часы; разница с сервером не должна превышать 5 минут.

401004

Request has already been used

При каждом повторе создавайте новый nonce и подпись.

403002

Request IP is not allowed

Сверьте публичный исходящий IP приложения с активным списком разрешённых адресов.

500003

Request signing verification is unavailable

Повторите с ограниченной задержкой и новым nonce/подписью. Если проблема сохраняется, обратитесь в поддержку.

Полный список и обработку HTTP см. в разделе Формат ответа.

Успешный повтор может оплачиваться снова: nonce предотвращает воспроизведение, а не повторное списание. Любой непустой заголовок подписи запускает проверку даже при отключённой подписи.

Ротация секрета

Создайте новый секрет в Security Settings, безопасно скопируйте его и выберите срок старого. Для применения ротации выберите Save Changes; создание несохранённого секрета не заменяет текущий.

  • In 24 hours: после сохранения оба секрета работают в переходный период. Обновите все приложения до истечения старого секрета.

  • Immediately: старый секрет перестаёт работать после сохранения. Используйте этот вариант при подозрении на раскрытие.

API-ключ не меняется. Пока идёт ротация, новую начать нельзя. Дождитесь истечения старого секрета или отзовите его досрочно. Досрочный отзыв немедленно отклоняет запросы, подписанные этим секретом.

Последнее обновление