> For the complete documentation index, see [llms.txt](https://docs.lumiid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumiid.com/getting-started/lumiid-api-authentication.md).

# LumiID API Authentication

## API Authentication

Authenticate each LumiID API request with an Application ID and Secret Key.

Keep your Secret Key on a secure server. Never expose it in client-side code.

### Before you begin

Create an application in the LumiID Dashboard before making requests.

1. Sign in to the dashboard.
2. Open **Settings → Applications**.
3. Create an application and save it.
4. Copy its Application ID and Secret Key.

Your Application ID identifies the application. Your Secret Key authorizes API access.

### Choose an environment

Use Sandbox while developing and testing. Use Production for live requests.

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

Always use HTTPS. Keep your credentials in the same environment as the request.

### Add authentication headers

Send these headers with every API request:

```http
Authorization: Bearer YOUR_SECRET_KEY
X-App-ID: YOUR_APPLICATION_ID
Content-Type: application/json
```

The `Authorization` value is case-sensitive. Include `Bearer` before the Secret Key.

### Send an authenticated request

This example verifies a Nigerian National Identification Number (NIN) in Sandbox.

```bash
curl --request POST \
  'https://sandbox-api.lumiid.com/v1/nin/verify' \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'X-App-ID: YOUR_APPLICATION_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "nin": "12345678901"
  }'
```

Replace the sample credentials before running the request. Use the Production base URL only after validation.

### Handle authentication errors

Authentication failures return an HTTP `401` status. Use the error `code` for application logic.

| Error code                | Meaning                                             | Resolution                                                  |
| ------------------------- | --------------------------------------------------- | ----------------------------------------------------------- |
| `INVALID_API_KEY`         | The key is missing, invalid, malformed, or revoked. | Copy a valid Secret Key from the dashboard.                 |
| `UNAPPROVED_ORGANIZATION` | The organization cannot access Production.          | Complete organization verification before using Production. |
| `SUBSCRIPTION_REQUIRED`   | The service is not enabled for your account.        | Enable the required verification service in the console.    |

Do not automatically retry authentication errors. Correct the configuration before retrying.

### Secure your credentials

Follow these practices in every environment:

* Store the Secret Key in environment variables or a secrets manager.
* Send requests only from your server or trusted backend.
* Never commit keys to source control or include them in logs.
* Rotate a key immediately if you suspect exposure.
* Use a separate application and credentials for each environment.

### Troubleshooting checklist

If authentication fails, verify the following:

1. The request uses the correct Sandbox or Production base URL.
2. `Authorization` includes `Bearer` and the current Secret Key.
3. `X-App-ID` matches the application that owns the Secret Key.
4. The organization and service have access to the requested endpoint.

### Next steps

Review [API response codes and error handling](/api-integration/technical-references/lumiid-api-error-codes-and-http-response-handling.md) for all API errors. Start with the [NIN verification API](/api-integration/government-verification/nin-verification-api-or-nigerian-national-id-lookup.md) when you are ready to integrate.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.lumiid.com/getting-started/lumiid-api-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.