Guide
Authentication
API keys, test and live mode, idempotency and rate limits.
API keys
Send your key as a bearer token on every request: Authorization: Bearer vk_test_…. Create keys in the console under Developers. A key is shown once, so store it as a secret on your server. Never put it in a mobile app or a web page.
| Key | What it reaches |
|---|---|
| vk_test_… | The sandbox: fictional identities only, no charge. Open as soon as you sign up. |
| vk_live_… | Real identity checks, billed to your wallet. Available once Verath approves your company. |
A missing, wrong or revoked key gets 401. Revoke a key from the same page at any time; it stops working straight away. Each check records which key made it, and the console’s request log shows every call.
Purpose and consent
Every check needs a purpose, recorded with the check:
| purpose | Use it for |
|---|---|
| KYC-ONB | Opening an account or onboarding a customer |
| KYC-REV | Periodic review of an existing customer |
| LEND | A credit or lending decision |
| EMPL | Employment screening |
Add consent_ref (your reference for the person’s consent) and customer_ref (your ID for the person). Checks with the same customer_ref are grouped under one customer in the console.
Safe retries
Send an Idempotency-Key header (up to 100 letters, digits, dots, dashes, colons or underscores) on checks. If you send the same key with the same body within 24 hours, you get the stored result back with Idempotent-Replayed: true and aren’t charged again. The same key with a different body gets 409 idempotency_conflict; a repeat while the first request is still running gets 409 idempotency_in_progress.
data_policy: "not_stored").Rate limits and request IDs
Each business has a per-minute limit. Over it, you get 429 rate_limited with a Retry-After header in seconds: wait that long, then retry. Every response carries a Request-Id header. Log it and quote it to support.