Authentication
Idova's public API authenticates with bearer API keys. No OAuth, no session cookies — just a key in the Authorization header.
Key format
idv_test_<ulid>.<secret> — sandbox
idv_live_<ulid>.<secret> — production
The secret is shown once at creation. If you lose it, revoke the key and create a new one.
Sending requests
GET /v1/kyc-requests HTTP/1.1
Host: api.idova.local
Authorization: Bearer idv_test_01K…
Sandbox vs live
Every API key is bound to one environment (sandbox or live). The environment is baked into the key prefix and propagated to every request. Sandbox and live data are fully isolated — separate applicants, separate KYC requests, separate webhook endpoints.
Use sandbox for: development, CI tests, UAT. No real decisions, no billing.
Use live for: production only. Decisions are final and audit-tracked.
Rate limits
| Tier | Requests per minute |
|---|---|
sandbox | 60 |
live — free | 60 |
live — starter | 300 |
live — pro | 1000 |
Limits are per-API-key. On exceed you get 429 Too Many Requests with a Retry-After header in seconds.
Key management
- Rotate regularly. Create a new key, deploy it, then revoke the old one.
- Never commit keys to source control. Load from environment variables or a secrets manager.
- One key per service. Make it easy to revoke without coordinating across services.
- Revocation is immediate. A revoked key returns
401 Unauthorizedon the next request.
Errors
| Status | Meaning |
|---|---|
401 missing_api_key | No Authorization header |
401 invalid_api_key | Malformed or unknown key |
401 revoked_api_key | Key was revoked |
403 wrong_environment | Using a sandbox key against a live resource or vice-versa |
429 rate_limited | Per-minute limit exceeded |