Security and Reliability Best Practices
Bitnob is designed to be programmable financial infrastructure. With stablecoins, you’re interacting with real money over public blockchains—so security, permission management, and reliability must be treated as core parts of your integration. This section outlines how to build a production-grade, fault-tolerant setup.
API Key Management
All access to Bitnob’s APIs is authenticated via Bearer tokens (secret keys). These keys are powerful and must be handled with care.
Best Practices:
Use separate keys for production, staging, and development
Rotate keys regularly via the Bitnob Dashboard
Never expose keys in frontend code, GitHub, or client apps
Keys are tied to a company account. You can generate and manage them in the API section of your dashboard.
Role-Based Scopes
Each key can be assigned granular scopes to limit access:
| Scope | Capability |
|---|---|
| wallet:read | View wallet balances and metadata |
| wallet:write | Create deposit addresses |
| transfer:create | Send stablecoins to addresses |
| webhook:read | View configured webhooks |
Apply least privilege: only give keys the permissions required for a specific service or microservice.
Webhook Security
Bitnob signs all webhook requests using a shared secret with HMAC SHA-256.
To verify a webhook:
Get the X-Bitnob-Signature header from the request
Hash the raw request body using your webhook secret
Compare the result with the header value (use constant-time comparison)
Why it matters: Prevents spoofed or replayed webhook attacks.
Transfer Integrity and Idempotency
Always use a unique reference per outbound transfer
Never initiate a second transfer until you’ve confirmed failure or completion of the first
Listen for transfer.failed and transfer.completed events for final state
Use internal locking if your app supports concurrent withdrawals
Access Control Recommendations
Enforce 2FA on all admin dashboards
Segment sensitive operations (like transfer:create) into separate services
Log all internal actions on your infrastructure: who initiated a transfer, who changed keys, etc.
If you operate a multi-tenant platform, make sure tenants cannot trigger transfers outside their scope
Reliability Patterns
| Failure | Pattern |
|---|---|
| API downtime | Queue and retry writes with backoff |
| Webhook outage | Allow replays or trigger from dashboard |
| Chain congestion | Alert on delayed confirmation, auto-prioritize fees |
| Transfer failure | Automatically trigger re-attempt logic only after validation |
Monitoring and Alerting
We recommend tracking the following for observability:
Transfer success and failure rates, per chain
Webhook delivery latencies and error rates
Wallet balance health (per token, per chain)
Key usage: high-frequency access or abuse patterns
Integrate these metrics into your monitoring stack (e.g., Datadog, Prometheus, Sentry).
Fraud Prevention Tips
Validate that user-provided wallet addresses match expected token standards (e.g., ERC-20 for Ethereum)
Require users to confirm high-value transfers with 2FA or passkeys
Set thresholds for withdrawals per account per day
Use reference checks to prevent double submission
Automatically flag withdrawals to newly created or unverified addresses
