Authentication

Authenticate securely with scoped test and live API keys.

Idyntic authenticates public API requests with environment-specific Bearer tokens.

Authorization header

Authorization: Bearer id_test_your_key

Use the exact Bearer scheme followed by one space and the API key.

Key environments

PrefixEnvironmentIdentity dataWallet charges
id_test_Test SandboxTest dataNo
id_live_Live ProductionLive dataYes

A key belongs to one environment. Test keys cannot access live data, and live keys do not return sandbox fixtures.

Scopes

ScopeRequired by
BALANCE_READGET /v1/balance
NIN_VERIFYAll NIN verification endpoints
BVN_VERIFYAll BVN verification endpoints

A missing scope returns HTTP 401 with UNAUTHORIZED.

Key lifecycle

  • The complete secret is shown once when the key is created or rotated.
  • Revoked and expired keys stop authenticating immediately.
  • An account can have up to 10 active keys.
  • Use separate keys for separate applications or deployment environments.
  • Rotate a key through the Developer Dashboard if it may have been exposed.

Secure storage

Store API keys in a server-side secret manager or environment variable. Never commit keys to source control, include them in logs, or ship them in frontend JavaScript or a mobile application.

❗

Treat live keys like payment credentials

A live key can initiate billable identity lookups against your wallet. Restrict access and revoke suspected credentials immediately.

Authentication failure

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Provide a valid API key with the NIN_VERIFY scope.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

The message names the scope required by the requested endpoint.


Did this page help you?