Authentication
How Truztcube authenticates requests — API keys (x-api-key) for the verification API, and JWT for the dashboard — plus how to generate, scope, and revoke keys.
Truztcube has two authentication models, for two different audiences:
| Model | Header | Used for |
|---|---|---|
| API key | x-api-key: sk_... | The verification API — your programmatic integration (NIN, BVN, biometrics, …). |
| JWT (bearer) | Authorization: Bearer <token> | The dashboard / account — signing in, managing your organisation, and generating API keys. |
Most integration work uses the API key. You only use the JWT flow to log in to the dashboard (or the account endpoints) to manage your keys.
API keys — the verification API
Pass your key in the x-api-key header on every verification request:
curl -X POST https://api.truztcube.com/v1/nin/raw/lookup \
-H "x-api-key: sk_test_your_key" \
-H "Content-Type: application/json" \
-d '{ "nin": "00000000000", "requestReason": "KYC" }'A request with a missing or invalid key is rejected with 401 before any verification runs.
Test vs live keys
| Key type | Prefix | Behaviour |
|---|---|---|
| Test | sk_test_ | Sandbox — real API, fixture data, no wallet debit. |
| Live | sk_live_ | Real registers, debits your wallet on a billable result. |
Generating and managing keys
Manage keys from the dashboard or the API-key endpoints:
POST /v1/api-keys— generate a key. Body:name,type(testorlive), optionalrateLimit, optionalexpiresInDays. The key secret is shown once on creation — store it securely.GET /v1/api-keys— list your keys (metadata only, never the secret).DELETE /v1/api-keys/{id}— revoke a key. Revocation is immediate.
Keep keys server-side
API keys are secrets. Never embed a live key in a browser, mobile app, or public repo. Revoke and rotate immediately if a key is exposed. Full contract in the API Reference.
Dashboard / account (JWT)
To sign in and manage your organisation, the account endpoints use email + password with an OTP step:
POST /v1/auth/login— submit credentials; triggers an OTP.POST /v1/auth/confirm-login— confirm with the OTP to receive your JWT.- Use
Authorization: Bearer <token>on account endpoints (/v1/auth/me, sessions, etc.). POST /v1/auth/refreshrenews the token; sessions can be listed and revoked.
Related
- Quick Start — from sign-up to first call.
- API Reference — every endpoint and schema.
Quick Start
From sign-up to your first Truztcube verification in a few minutes — get an API key, make a NIN lookup, read the result, then go live.
ID Verification
Verify a NIN or BVN against the source register and return the holder's record — with all the NIN lookup modes and BVN tiers Truztcube supports.