Authentication
API key usage, scopes, and environments.
API Keys
All API requests require a Bearer token in the Authorization header:
Authorization: Bearer cusd_test_7kB9mR2xPqLw...
Keys are generated on the API Keys page. The full key is shown once at creation — store it securely. We only store a SHA-256 hash.
Environments
Overvoid uses a single API endpoint for both environments. The key prefix determines whether you're in sandbox or production:
| Prefix | Environment | Network |
|---|---|---|
cusd_test_ | Sandbox | Sepolia, Arb Sepolia, Base Sepolia |
cusd_live_ | Production | Ethereum, Arbitrum, Base |
Both key types use https://api.overvoid.io. The environment is locked to the key — a cusd_test_ key can only see and create sandbox data, and a cusd_live_ key can only see and create production data. This cannot be overridden.
Data Isolation
Live and test environments share the same API and database, but data is fully partitioned. Every resource (entities, alerts, cases, transfers, compliance checks) is tagged with an environment. Queries automatically filter by the key's environment — test data never appears in live responses and vice versa.
This means you can build and test your full integration against the sandbox without any risk of affecting production data. When ready, switch to a cusd_live_ key — no code changes needed, just a different key.
Sandbox Behavior
The sandbox environment is functionally identical to production with a few key differences:
| Feature | Sandbox Behavior |
|---|---|
| Screening | Returns deterministic mock results instead of calling real providers. Name an entity with “FAIL” to test failure paths. |
| Monitoring | All 33 rules evaluate normally. Alerts are created but don't trigger real blockchain freezes. |
| SAR/CTR Filing | Full drafting, XML generation, and validation works. Final FinCEN submission is blocked. |
| Onboarding | Full workflow including all status transitions (pending, active, suspended, revoked). |
| Blockchain | Connects to Sepolia testnets. Contract addresses are identical across all testnets (CREATE2). |
Mock responses include "sandbox": true so you can distinguish them programmatically. See the Sandbox page for testnet contract addresses and pre-funded wallets.
Scopes
Each API key has a set of scopes that control which endpoints it can access. Create keys with minimal scopes for least-privilege access.
| Scope | Access |
|---|---|
read | Read entities, compliance status, and transaction receipts |
transfers | Ingest transfers, view transfer history |
onboarding | Create and manage entities, wallets, verification |
compliance | Initiate transfers with travel rule data, check compliance |
webhooks | Manage webhook endpoints and view deliveries |
IP Allowlisting
Optionally restrict API key usage to specific IP addresses or CIDR ranges. Requests from non-allowed IPs will receive a 403 Forbidden response.
Configure IP allowlists on the Settings page. Both IPv4 and IPv6 addresses are supported, with optional CIDR notation (e.g. 192.168.1.0/24).
Error Responses
Authentication errors return standard HTTP status codes:
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Key valid but insufficient scope, IP not in allowlist, or key revoked |
429 | Rate limit exceeded (see Rate Limits) |