API Keys

API keys authenticate your application's requests to the Lira verification API — each key is scoped to an environment (sandbox or live) and belongs to your organisation.

Before you start

API key management requires a JWT Bearer token in the Authorization: Bearer header. See Authentication if you need to obtain or refresh one.

Required roles

Action	Minimum role
Create a key	`ORG_ADMIN`
List keys	`ORG_ADMIN` or `DEVELOPER`
Revoke a key	`ORG_ADMIN`

Create an API key

curl -X POST https://api.lira.com/api/v1/client/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production server",
    "environment": "live"
  }'

Request body

Field	Type	Required	Description
`name`	string	Yes	A human-readable label to identify this key (e.g. "Production server", "Staging").
`environment`	string	Yes	`sandbox` or `live`. Controls which environment the key operates in.

Response 201 Created

{
  "id": "3f4a1b2c-...",
  "name": "Production server",
  "key": "lira_live_a3f08c1d4e2b9f3c...",
  "keyPrefix": "lira_live_a3f08c...",
  "environment": "live",
  "createdAt": "2026-03-09T10:00:00.000Z",
  "warning": "Save this key securely. It will not be shown again."
}

Warning: The key field is only returned once. Copy it immediately and store it in an environment variable or secrets manager. It cannot be retrieved again after this response. If you lose it, you must revoke the key and create a new one.

Key format

Keys follow the pattern lira_{environment}_{32-byte hex}:

lira_sandbox_a3f08c1d4e2b9f3c1e5d7a8b2c4f6e0d1a3b5c7d9e1f3a5b7c9d1e3f5a7b9c

The keyPrefix (e.g. lira_sandbox_a3f0...) is retained for display purposes. Use it in the dashboard or list responses to identify which key is in use without exposing the full value.

Authenticate requests with an API key

Pass the key in the X-API-Key header on every verification request:

curl -X POST https://api.lira.com/api/v1/verify/account \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0123456789",
    "country": "NG",
    "bankCode": "044"
  }'

API keys are used only for verification endpoints (/verify/...). Dashboard and management endpoints (/client/...) require a JWT Bearer token.

List API keys

Returns all keys for your organisation. The full key value is never included in list responses — only the keyPrefix.

curl https://api.lira.com/api/v1/client/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response 200 OK

[
  {
    "id": "3f4a1b2c-...",
    "name": "Production server",
    "keyPrefix": "lira_live_a3f08c...",
    "environment": "live",
    "isActive": true,
    "lastUsedAt": "2026-03-09T09:45:00.000Z",
    "expiresAt": null,
    "createdAt": "2026-03-01T10:00:00.000Z"
  }
]

Field	Description
`id`	Unique key ID — use this to revoke the key
`name`	The human-readable label set at creation
`keyPrefix`	Display prefix for identification
`environment`	`sandbox` or `live`
`isActive`	`false` if the key has been revoked
`lastUsedAt`	Timestamp of the most recent request using this key
`expiresAt`	Expiry date if set, otherwise `null`

Revoke an API key

Revoked keys are rejected immediately for all subsequent requests.

curl -X DELETE https://api.lira.com/api/v1/client/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response 204 No Content

Note: Revocation is permanent. To restore access, create a new API key and update your application's environment variables.

Key security

Warning: Never embed API keys in client-side code, mobile app binaries, or browser JavaScript. API keys must only be used server-side. If a key is exposed in client-side code, it can be extracted and abused by anyone.

Warning: Never commit API keys to version control. Add your .env file to .gitignore and use a secrets manager for production deployments. If a key is accidentally committed, revoke it immediately — treat it as compromised regardless of whether the repository is private.

Important: Use separate keys for separate environments. Never use a live key in development or staging code. Use separate environment variables (e.g. LIRA_API_KEY_SANDBOX and LIRA_API_KEY_LIVE) to keep them clearly separated.

Key rotation

Rotate your API key when:

A key may have been exposed (in logs, a git commit, an error message, etc.)
A team member with key access leaves your organisation
Your security policy requires periodic rotation

To rotate a key:

Create a new API key with the same environment and name:

curl -X POST https://api.lira.com/api/v1/client/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production server (rotated)",
    "environment": "live"
  }'

Store the new key value in your secrets manager or environment variable.
Deploy the updated environment variable to your application.
Revoke the old key using its id (visible in GET /client/api-keys):

curl -X DELETE https://api.lira.com/api/v1/client/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Note: Update your application with the new key before revoking the old one to avoid downtime. Revocation takes effect immediately.

Sandbox vs live

Environment	Purpose	Key prefix
`sandbox`	Development and testing — no real verifications processed	`lira_sandbox_...`
`live`	Production traffic — real provider queries, billed per verification	`lira_live_...`

See Environments for sandbox test data and switching instructions.

Next steps

Authentication — obtain and refresh the Bearer token needed to manage API keys
Environments — understand the difference between sandbox and live, and how to switch
Go Live — key security checklist before switching to production

Environments

Supported Countries