Получение токенов доступа, ротация секретов подписей верификации и защита API в Syncra V2

Управление API-ключами и безопасностью

Для взаимодействия с Syncra Merchant API V2 вашему приложению требуются авторизационные данные (API Credentials). Платформа использует раздельные ключи для идентификации запросов от мерчанта к шлюзу и для верификации входящих уведомлений (вебхуков) от шлюза к мерчанту.

Типы ключей доступа

API Token (Токен мерчанта):
- Уникальная строка (64 шестнадцатеричных символа), используемая в качестве публичного идентификатора.
- Передается в заголовке X-Merchant-Token при каждом запросе к API.
- Используется для авторизации запросов и определения прав доступа мерчанта.
Webhook Secret (Секрет подписи):
- Приватный криптографический ключ (32-байтный секрет), используемый для вычисления HMAC-SHA256 подписей.
- Никогда не передается по сети в открытом виде.
- Применяется мерчантом для генерации подписи X-Signature при отправке запросов и для верификации подписи X-Syncra-Signature при получении вебхуков.
- Отображается в панели управления только один раз при создании или ротации.

Получение API-ключей

Выпуск ключей доступа осуществляется в личном кабинете администратора платформы (Admin Cabinet) или через специализированный эндпоинт выпуска:

POST /api/v1/p2p/merchant/api-keys

Пример ответа (`200 OK`)

{
  "data": {
    "merchant_id": "8f870a31-b88d-4cb0-a882-628d08cbda88",
    "api_token": "a1b2c3d4e5f607182930a4b5c6d7e8f901a2b3c4d5e6f7081920a3b4c5d6e7f8",
    "webhook_secret": "whsec_920ab3e09819cd8e412cfab9e87d0c3c",
    "created_at": "2026-07-12T17:20:00Z"
  }
}

Важно: Сохраните значение webhook_secret в надежном и зашифрованном хранилище конфигурации вашего приложения. После закрытия окна просмотра секрет больше не будет доступен для чтения в целях безопасности.

Ротация API-ключей (Token Rotation)

В случае компрометации токена или согласно регламенту безопасности вашей компании (например, раз в 90 дней), вы должны выполнить ротацию ключей.

POST /api/v1/p2p/merchant/api-keys/rotate

Двойное окно действия ключей (Grace Period)

Чтобы избежать сбоев в работе интеграции при ротации ключей, Syncra V2 поддерживает механизм Grace Period длительностью 15 минут:

После успешного запроса ротации система генерирует новую пару «токен + секрет».
В течение 15 минут шлюз продолжает принимать запросы, подписанные как старым, так и новым ключом.
Это дает вашему приложению время на безопасное обновление конфигурационных файлов и перезапуск сервисов без простоя (Zero-Downtime Migration).

Экстренное отключение (API Kill-Switch)

Если вы обнаружили утечку ключей или несанкционированные транзакции, вы можете мгновенно заблокировать все API-запросы с помощью функции Kill-Switch.

Запрос может быть отправлен через Admin API (или выполнен вручную администратором в панели):

POST /api/v1/p2p/merchants/{merchant_id}/kill-switch

Параметры запроса (JSON Body)

{
  "active": true,
  "reason": "Compromised API keys detected"
}

После активации блокировки все последующие запросы к API скомпрометированного мерчанта будут немедленно отклоняться шлюзом с ошибкой 403 Forbidden и детальным кодом MERCHANT_DISABLED.

Безопасность хранения ключей

Никогда не храните API-токен и Webhook Secret в исходном коде вашего приложения (Hardcoded Keys).
Используйте переменные окружения (ENV) или специализированные менеджеры секретов (HashiCorp Vault, AWS Secrets Manager, Google Secret Manager).
Ограничьте доступ к конфигурационным файлам на ваших серверах.
Используйте функцию IP Whitelisting в личном кабинете для ограничения списка серверов, которым разрешено выполнять запросы с вашим токеном.

Управление API-ключами

On this page