Skip to main content
Every request to the LumiID API must be authenticated. LumiID uses Bearer Token authentication — you pass your Secret Key in the Authorization header of each request, and your Application ID in the X-App-ID header. Together, these two credentials identify your application and authorize access to the API. Your Secret Key must stay on your server at all times; never send it from a browser, mobile app, or any client-side environment.

​
Before You Begin

You need an active LumiID application to generate credentials. If you haven’t created one yet, follow these steps:
1

Sign in to the LumiID Dashboard

Go to lumiid.com and sign in with your account credentials.
2

Open Settings → Applications

From the left sidebar, navigate to Settings → Applications.
3

Create an Application

Click Create Application. Provide an application name, an optional description, and an optional logo. Save the application.
4

Copy Your Credentials

After saving, copy both your Application ID and Secret Key. Store them securely — you’ll need both for every authenticated API request.
Your Application ID identifies the application making the request. Your Secret Key authorizes API access. Keep the Secret Key on a secure server and never expose it in client-side code.

​
Environments

LumiID provides two environments. Use Sandbox while building and testing; switch to Production only after your integration has been validated. Always send requests over HTTPS. Keep your credentials in the same environment as the request — don’t use a Sandbox key against a Production endpoint, or vice versa.

​
Authentication Headers

Include these three headers with every API request:
The Authorization value is case-sensitive. You must include the word Bearer followed by a single space before your Secret Key. Omitting Bearer or adding extra characters will result in a 401 INVALID_API_KEY error.

​
Example Authenticated Request

The following example verifies a Nigerian NIN in the Sandbox environment. Replace the placeholder credentials with your actual Application ID and Secret Key before running the request.
cURL
Use the Production base URL only after your integration has been fully validated in Sandbox.

​
Tracking Requests with customer_reference

For easier debugging and auditing in production, attach a unique reference to each API request using the customer_reference query parameter. This value appears in your API logs and dashboard, making it simple to trace individual transactions back to your own records.
You can use any unique value that maps back to your system:
  • Transaction ID
  • Customer ID
  • Order Number
  • Session ID
  • Invoice Number
Using customer_reference is strongly recommended for production integrations. It speeds up support investigations and simplifies compliance audits.

​
Authentication Error Codes

Authentication failures return an HTTP 401 status. Use the code field in the response body for your application logic — do not automatically retry 401 errors. Correct the configuration first, then retry.

​
Security Best Practices

Protect your credentials in every environment by following these guidelines:
  • Store credentials in environment variables — use .env files locally and your hosting platform’s secrets manager in production. Never hardcode keys in source files.
  • Send requests server-side only — your Secret Key must never appear in frontend JavaScript, mobile app code, or any environment accessible to end users.
  • Keep keys out of source control — add .env to your .gitignore. Scan your repositories before making them public.
  • Rotate immediately if compromised — if you suspect a key has been exposed, regenerate it straight away from Settings → API Keys → Regenerate. The old key is invalidated instantly.
  • Use separate credentials per environment — create a distinct application for Sandbox and a separate one for Production. This prevents accidental cross-environment requests.
If you accidentally commit a Secret Key to a public repository, regenerate it immediately. Do not simply delete the commit — treat the key as permanently compromised.

​
Troubleshooting Checklist

If your requests are returning 401 Unauthorized, work through this checklist before contacting support:
  1. Check the base URL — confirm you’re using the correct Sandbox or Production URL for the environment you’re targeting.
  2. Check the Authorization header format — it must read Bearer YOUR_SECRET_KEY with Bearer capitalized and a single space before the key.
  3. Check the X-App-ID header — confirm it matches the Application ID for the application that owns the Secret Key you’re using.
  4. Check your organization status — if you’re hitting Production endpoints, ensure your organization has completed the verification and approval process in the dashboard.
  5. Check service activation — if you’re receiving SUBSCRIPTION_REQUIRED, navigate to the LumiID Console and enable the specific verification service (e.g., NIN, BVN, AML Screening) for your account.
  6. Check for key expiry or regeneration — if someone on your team recently regenerated the key, update your environment variables to the new value.

​
Next Steps

Once authentication is working, you’re ready to call any LumiID verification endpoint. Start with the resources below: