API authentication

Security

API authentication

BroSettlement API authentication uses asymmetric Ed25519 keys. Your backend signs each request with a private key, and BroSettlement verifies it with the registered public key.

Required headers

HeaderDescription
X-Bro-Api-KeyAPI key identifier
X-Bro-TimestampISO 8601 timestamp for replay protection
X-Bro-NonceUnique value per request
X-Bro-SignatureBase64-encoded Ed25519 signature

Signature payload

Build the signature payload from the request method, path, timestamp, nonce, and body hash.

text
METHOD
/v1/wallets
2026-06-25T09:00:00Z
8f7b8f24-4e6a-45d2-a944-4b11c4c7d2f8
sha256_body_hash

Security controls

  • Use Ed25519 key pairs for API authentication.
  • Store private keys in a secrets manager or HSM-backed service.
  • Rotate keys when access ownership changes.
  • Enable IP whitelisting for production API keys.
  • Enforce unique nonces for replay protection.
  • Keep timestamps within the accepted request window.
  • Use mandatory 2FA for all human users.

Example request

bash
curl https://api.brosettlement.com/v1/wallets \
  -H "X-Bro-Api-Key: api_key_123" \
  -H "X-Bro-Timestamp: 2026-06-25T09:00:00Z" \
  -H "X-Bro-Nonce: 8f7b8f24-4e6a-45d2-a944-4b11c4c7d2f8" \
  -H "X-Bro-Signature: base64_ed25519_signature" \
  -H "Content-Type: application/json" \
  -d '{"organizationId":"org_123","chain":"ETH","label":"Treasury wallet"}'

Common failures

ErrorCauseFix
invalid_signatureSignature does not match the canonical requestRebuild the payload and verify body hashing
expired_timestampRequest timestamp is outside the allowed windowSync server time with NTP
duplicate_nonceNonce was already usedGenerate a unique nonce for each request
ip_not_allowedRequest came from an unlisted IPUpdate the API key IP whitelist