Keys & authentication

Keys look like nw_live_ or nw_test_ followed by 32 random characters (letters and digits). The portal shows a key exactly once; we store only its SHA-256 hash and a short display prefix such as nw_live_3fQa.

Sending the key

X-API-Key: nw_live_…          # preferred
Authorization: Bearer nw_live_…  # also accepted
?key=nw_live_…                # last resort — ends up in logs and caches

/v2/meta/* needs no key. New, revoked and re-planned keys take effect within 30 seconds.

Live and test keys

	live	test
Counts to your monthly quota	yes	no — own cap of 1,000 units/month per key
Burst	your plan’s limit	at most 5 requests/s
Billed (paid plans, later)	yes	never

Apps and restrictions

Every key belongs to an app. The app’s platform decides which checks apply, and the app holds the default restrictions for its keys. A key can override a list with its own (e.g. a staging origin); a key without its own list always follows the app, including later changes.

Platform	Key is…	Restriction
server	secret	none — keep it in your backend
web	publishable	allowed origins, checked against the browser’s `Origin` when it is sent (`https://*.example.com` works)
ios	publishable	bundle IDs; every request must send `X-Ios-Bundle-Identifier`
android	publishable	package names; every request must send `X-Android-Package`

Bundle IDs are enforced. When a key has bundle IDs (its own list, else its app’s), a request without the header gets 403 bundle-required, one with a different ID 403 bundle-not-allowed. A * matches one or more characters including dots: com.example.app.* admits all nested IDs (extensions, widgets) but not com.example.app itself — list both if you need both.

Origins are advisory. They are checked only when an Origin header is present (403 origin-not-allowed if it doesn’t match); a server-side caller sends none. Keys without origins or bundle IDs (server keys) are not restricted.

These checks stop casual reuse of a key that ships inside an app or website, not a determined attacker. Mobile keys also get a per-install burst limit — send a random, persistent X-Install-Id per installation (fallback: client IP). Device attestation (App Attest / Play Integrity) is planned.

Scopes

By default a key may use every endpoint your plan includes (also after an upgrade). Narrow it to what the client needs — e.g. only weather for a mobile app. A request outside the key’s scopes gets 403 scope-missing; outside the plan 403 plan-feature-missing.

Rotation and revocation

Rotate creates a new key with the same settings and lets the old one expire after an overlap you choose (immediately, 1 hour … 30 days).
Revoke stops a key within 30 seconds (401 key-revoked). It cannot be undone.
Keys can carry an expiry date (401 key-expired afterwards).
Archiving an app is a reversible soft delete: all its keys answer 401 app-archived until the app is restored.