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

# Publishable keys

> Client-side API keys for the embeddable widget.

Publishable keys (`nipost_pk_test_…` / `nipost_pk_live_…`) are API keys designed
to ship inside client-side code — web pages, mobile binaries — where anyone can
read them. They are safe to embed because they are tightly constrained:

| Constraint       | Value                                                 |
| ---------------- | ----------------------------------------------------- |
| Scopes           | `search`, `lookup`, `widget` only                     |
| Max lookup level | 3 (no building-owner info, no point geometry)         |
| Browser use      | Only from origins on the key's allowlist              |
| Rate limits      | Per key **and** per IP per key                        |
| Metering         | Widget sessions and lookups debit your credit balance |
| Revocation       | Immediate, from the dashboard                         |

Create one in the dashboard (**Settings → API Keys → Publishable**), listing
every web origin that will embed the widget, e.g. `https://checkout.acme.ng`.
Native mobile apps send no `Origin` header, so the allowlist only gates
browsers.

## Threat model

Anyone holding your publishable key can start widget sessions and, given a
person's NIN or email, list that person's bookmark labels and postcodes. That
exposure is bounded by design — minimal fields, anti-enumeration responses,
rate limits, hashed-identifier audit logs, credit metering — but you should
still:

* keep separate test and live keys, and rotate if a key leaks beyond your app;
* never grant a publishable key more scopes or level than it needs;
* use a **secret** key server-side instead whenever a browser is not involved.