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
| Header | Description |
|---|---|
X-Bro-Api-Key | API key identifier |
X-Bro-Timestamp | ISO 8601 timestamp for replay protection |
X-Bro-Nonce | Unique value per request |
X-Bro-Signature | Base64-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_hashSecurity 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
| Error | Cause | Fix |
|---|---|---|
invalid_signature | Signature does not match the canonical request | Rebuild the payload and verify body hashing |
expired_timestamp | Request timestamp is outside the allowed window | Sync server time with NTP |
duplicate_nonce | Nonce was already used | Generate a unique nonce for each request |
ip_not_allowed | Request came from an unlisted IP | Update the API key IP whitelist |