Security Architecture
Core Security Principles
API Key Security
API keys are the primary authentication mechanism. ZendFi applies defense-in-depth:- Hashing: Keys are hashed with SHA-256 for fast lookup, then verified with Argon2id for brute-force resistance. The raw key is never stored.
- Mode isolation: Test keys (
zfi_test_) and live keys (zfi_live_) operate in completely separate environments. A test key cannot access production data or create real transactions. - Prefix identification: The key prefix (
zfi_test_orzfi_live_) tells you the mode at a glance without exposing the secret portion. - Rotation: Keys can be rotated instantly through the API or CLI. The old key is invalidated immediately.
Webhook Verification
Every webhook includes an HMAC-SHA256 signature in theX-ZendFi-Signature header. This guarantees:
- Authenticity — The event came from ZendFi, not a spoofed source.
- Integrity — The payload has not been tampered with in transit.
- Freshness — The timestamp prevents replay attacks.
Transport Security
All communication with the ZendFi API is over HTTPS (TLS 1.3). The SDK and CLI enforce HTTPS and will reject plaintext connections.On-Chain Security
Payments are settled on Solana, which provides:- Immutability — Confirmed transactions cannot be reversed.
- Transparency — Every transaction is publicly verifiable on the blockchain.
- Gasless transactions — ZendFi sponsors gas fees so customers do not need SOL for token transfers.
Threat Model
| Threat | Mitigation |
|---|---|
| API key theft | SHA-256 + Argon2 hashing, key rotation, mode isolation |
| Webhook spoofing | HMAC-SHA256 signature verification |
| Replay attacks | Timestamp validation, idempotency keys |
| Man-in-the-middle | TLS 1.3 enforced on all endpoints |
| Brute-force attacks | Rate limiting (100 req/min general, 10/min for key operations) |
| Duplicate payments | Idempotency keys with 24-hour window |
| Unauthorized access | Bearer token authentication on every request |
Your Responsibilities
While ZendFi handles platform-level security, you are responsible for:API Key Storage
Store keys in environment variables or a secrets manager. Never hardcode keys in source code or commit them to version control.
Webhook Verification
Always verify webhook signatures before processing events. The SDK handlers do this automatically.
HTTPS Endpoints
Ensure your webhook endpoint uses HTTPS. ZendFi will not deliver webhooks to plaintext HTTP URLs in production.
Access Control
Implement proper authorization in your application. ZendFi authenticates the API request, but you must authorize user actions.