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 organization.

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

Terminal

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

JSON

{
  "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}:

Text

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:

Terminal

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": "000014"
  }'

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 organization. The full key value is never included in list responses, only the keyPrefix.

Terminal

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

Response 200 OK

JSON

[
  {
    "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.

Terminal

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.

Warning

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 organization
Your security policy requires periodic rotation

To rotate a key:

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

Terminal

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):

Terminal

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 external 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

← PreviousMembers & Invitations Next →Usage Statistics