Автентифікація API

Безпека

Автентифікація API

BroSettlement використовує асиметричні Ed25519-ключі: backend підписує запит приватним ключем, а BroSettlement перевіряє його зареєстрованим публічним ключем.

Обов’язкові headers

HeaderОпис
X-Api-Key-IdUUID API key
X-Api-TimestampUnix timestamp у секундах UTC
X-Api-NonceУнікальний nonce для replay protection
X-Api-SignatureСтандартний padded Base64 Ed25519 signature
X-Api-Body-HashLowercase SHA-256 hex точних body bytes; потрібен для задокументованих mutations

Payload підпису

text
METHOD
EXACT_REQUEST_TARGET
BODY_HASH
TIMESTAMP
NONCE
API_KEY_ID

EXACT_REQUEST_TARGET — raw path і query точно у відправленому вигляді. Для request без body bytes третій рядок залишається порожнім. Для body request обчисліть hash точних raw bytes.

Засоби захисту

  • Ed25519 API authentication.
  • Secrets manager або HSM-backed service для приватних ключів.
  • Ротація ключів, IP allowlist та унікальні nonces.
  • Допустиме вікно timestamp.
  • Обов’язкова 2FA для людей-користувачів.

Приклад запиту

text
GET
/api/v1/assets?chain=tron%3Anile

1785402000
8f7b8f24-4e6a-45d2-a944-4b11c4c7d2f8
11111111-2222-4333-8444-555555555555

Порожній третій рядок означає відсутній body. Підпишіть точний текст, а потім передайте ті самі timestamp, nonce і key ID у headers.

Типові помилки

ПомилкаПричинаВиправлення
INVALID_SIGNATUREПідпис не відповідає canonical requestЗбережіть точний request target і body bytes
CLOCK_SKEW або INVALID_TIMESTAMPTimestamp некоректний або поза допустимим вікномСинхронізуйте час через NTP
REPLAY_DETECTEDNonce вже використаноГенеруйте унікальний nonce для кожного request
BODY_HASH_MISMATCHHeader hash відрізняється від отриманого bodyОбчислюйте hash точних serialized bytes
IP_NOT_ALLOWEDIP відсутній в allowlistОновіть IP allowlist ключа
INSUFFICIENT_SCOPEAPI key не має необхідного scopeНадайте мінімально необхідний scope