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

# Authentication

> API keys, scopes, access levels and rate limits.

## API keys

Authenticate by sending your key in the `X-API-Key` header:

```bash theme={null}
curl "https://api.postcode.gov.ng/v1/lookup?code=EK-01-A03-FK-01&level=2" \
  -H "X-API-Key: nipost_live_xxx"
```

Keys are created in the dashboard (**Settings → API Keys**). The secret is shown **once** at
creation. Keys come in two environments:

| Prefix          | Environment                  |
| --------------- | ---------------------------- |
| `nipost_test_…` | Test                         |
| `nipost_live_…` | Live (requires verified KYB) |

## Scopes & access levels

Each key carries **scopes** (`search`, `lookup`) and a **max lookup level** (1–5). A key can
never exceed the level granted to your organization — request higher access under
**Settings → KYB & Access**.

| Resource         | Requirement                                          |
| ---------------- | ---------------------------------------------------- |
| Search, Assembly | Public (no key)                                      |
| Lookup L1        | Public (no key)                                      |
| Lookup L2–L4     | Key with `lookup` scope + sufficient level (credits) |
| Lookup L5        | Restricted (granted on review)                       |

## Rate limits

Requests are rate-limited per key. Each response includes:

```
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
```

Exceeding the limit returns `429 Too Many Requests`.

## Errors

Errors use a consistent envelope:

```json theme={null}
{ "error": { "code": "insufficient_credits", "message": "not enough credits; top up to continue" } }
```

| Status | Meaning                                                           |
| ------ | ----------------------------------------------------------------- |
| `401`  | Missing/invalid API key, or auth required for the requested level |
| `403`  | Key lacks the scope or level for this request                     |
| `402`  | Insufficient credits                                              |
| `429`  | Rate limit exceeded                                               |