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

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

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

1. API Token (Токен мерчанта):

   • Уникальная строка (64 шестнадцатеричных символа), используемая в качестве публичного идентификатора.
   • Передается в заголовке X-Merchant-Token при каждом запросе к API.
   • Используется для авторизации запросов и определения прав доступа мерчанта.

2. Webhook Secret (Секрет подписи):

   • Приватный криптографический ключ (32-байтный секрет), используемый для вычисления HMAC-SHA256 подписей.
   • Никогда не передается по сети в открытом виде.
   • Применяется мерчантом для генерации подписи X-Signature при отправке запросов и для верификации подписи X-Signature при получении вебхуков.
   • Отображается в панели управления только один раз при создании или ротации.

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

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

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

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

Поля ответа — token и secret (верхний уровень, без обёртки data; НЕ api_token / webhook_secret):

{
  "token": "a1b2c3d4e5f607182930a4b5c6d7e8f901a2b3c4d5e6f7081920a3b4c5d6e7f8",
  "secret": "whsec_920ab3e09819cd8e412cfab9e87d0c3c"
}

Версия API (api_version)

При создании мерчанта или его редактировании в панели администратора доступен параметр API Version (Версия API):

• API V2 (по умолчанию): Полноценное новое API Syncra V2 с поддержкой копеек, HMAC-SHA256, буквенных кодов валют.
• API V1 (режим совместимости): Эмулирует поведение старой платформы (HMAC-SHA512, разделители ;, кодирование статусов целыми числами). Используется для бесшовной миграции без изменения кода мерчанта.

Для бесшовного перехода со старого шлюза выберите версию v1 при регистрации мерчанта.

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

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

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

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

Ротация возвращает новую пару в тех же полях token / secret (верхний уровень, без обёртки data; НЕ api_token / webhook_secret):

{
  "token": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
  "secret": "whsec_1f2e3d4c5b6a7988071625344352f1e0d0c9b8a7f6e5d4c3b2a190807"
}

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

Grace Period — подтверждённое поведение платформы (задеплоено; проверено живым E2E): после успешной ротации действует окно длительностью 15 минут, в течение которого шлюз принимает запросы как по новой, так и по старой паре ключей:

• После запроса ротации система атомарно генерирует новую пару «токен + секрет» — она валидна немедленно.
• Старая пара остаётся валидной до 15 минут, что даёт вашему приложению время на безопасное обновление конфигурации и перезапуск сервисов без простоя (Zero-Downtime Migration).
• Окно строго pair-scoped: валидна только целиком старая пара (старый токен + старый секрет). Смешанные комбинации (старый токен + новый секрет или наоборот) отклоняются с 401 Unauthorized.
• Исходящие вебхуки с момента ротации подписываются новым секретом немедленно — не ждите окончания окна для верификации колбэков.
• Длительность окна настраивается оператором через переменную окружения MERCHANT_KEY_GRACE_PERIOD; значение 0 полностью отключает окно (ротация мгновенно «убивает» старую пару).

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

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

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

• Это toggle без тела: каждый вызов переключает состояние (заблокирован ↔ разблокирован) и возвращает объект мерчанта с актуальным kill_switch. Отдельных полей запроса (active/reason) у эндпоинта нет.
• Admin-only: эндпоинт доступен только JWT-сессии оператора платформы (роль admin/platform_admin). HMAC-пара и кабинетная сессия мерчанта получают 403 Permission Denied («admin role required») — мерчант не может отключить сам себя; при подозрении компрометации запросите ротацию ключей и блокировку у оператора.
• Пока kill-switch активен, каждый запрос API этого мерчанта отклоняется с 403 Forbidden (merchant is disabled). Статус и причина блокировки видны мерчанту в кабинете: GET /api/v1/p2p/my-merchant → поля kill_switch / kill_switch_reason (см. My Merchant).

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

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