Authentication

API keys

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

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 and two kinds:

Prefix	Environment	Kind
`nipost_test_…`	Test	Secret (server-side only)
`nipost_live_…`	Live (requires verified KYB)	Secret (server-side only)
`nipost_pk_test_…`	Test	Publishable (may ship in client code)
`nipost_pk_live_…`	Live (requires verified KYB)	Publishable (may ship in client code)

Secret keys must never reach a browser or mobile binary. Publishable keys are built for exactly that: they are capped at lookup level 3, limited to the search, lookup and widget scopes, and — in browsers — only usable from the origins on the key’s allowlist. See Publishable keys.

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:

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

Getting started

Concepts

Widget

API keys

Scopes & access levels

Rate limits

Errors

​API keys

​Scopes & access levels

​Rate limits

​Errors

API keys

Scopes & access levels

Rate limits

Errors