> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumiid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate with the LumiID API

> Secure every LumiID API request with your Application ID and Secret Key. Learn how to get your keys, pass auth headers, and handle authentication errors.

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](https://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.

> [!NOTE]
>
> 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.

| Environment | Base URL |
| - | - |
| **Sandbox** | `https://api.lumiid.com/v1` |
| **Production** | `https://api.lumiid.com/v1` |

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:

```http theme={null}
Authorization: Bearer YOUR_SECRET_KEY
X-App-ID: YOUR_APPLICATION_ID
Content-Type: application/json
```

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.

```bash cURL theme={null}
curl --request POST \
  'https://api.lumiid.com/v1/ng/nin-basic/' \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'X-App-ID: YOUR_APPLICATION_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "nin": "89184072280"
  }'
```

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.

```
POST https://api.lumiid.com/v1/ng/nin-basic/?customer_reference=TXN-00123456
```

You can use any unique value that maps back to your system:

* Transaction ID
* Customer ID
* Order Number
* Session ID
* Invoice Number

> [!TIP]
>
> 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.

| Error Code | Meaning | Resolution |
| - | - | - |
| `INVALID_API_KEY` | The Secret Key is missing, invalid, malformed, or has been revoked. | Copy a valid Secret Key from the dashboard under **Settings → API Keys**. |
| `UNAPPROVED_ORGANIZATION` | Your organization has not been approved to access the Production environment. | Complete organization verification in the dashboard before switching to Production. |
| `SUBSCRIPTION_REQUIRED` | The verification service you're calling is not enabled on your account. | Enable the required verification service from the LumiID Console. |

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

> [!WARNING]
>
> 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:

* [NIN Verification API](https://docs.lumiid.com/api-reference/nin-verification) — Verify Nigerian National Identification Numbers against NIMC records
* [BVN Verification API](https://docs.lumiid.com/api-reference/bvn-verification) — Verify Bank Verification Numbers against CBN data
* [API Error Codes](https://docs.lumiid.com/reference/error-codes.md) — Full reference for all response codes and HTTP status handling


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.