[postio]
Get an API key
Docs

Authentication

Postio authenticates every request with an API key sent in the x-api-key header. Keys are scoped per service and can be locked to specific origins or IP ranges from the dashboard.

Sending your key

Put your key in the x-api-key header on every request. Keys have the form pk_ followed by 32 hex characters — there is no _live_ or _test_ infix.

curl "https://api.postio.co.uk/v1/address/search?q=57+wimpole+street" \
  -H "x-api-key: pk_..."

A missing or invalid key returns 401. A key that is out of credit returns 402 — top up to resume billable requests.

Verify a key with /connect

GET /connect

A free key and health probe. It returns 200 if the key is active and the upstream search service is reachable, with a requestId and timing in meta. Use it to confirm a key works, or as a lightweight heartbeat — it is never billed.

curl "https://api.postio.co.uk/v1/connect" \
  -H "x-api-key: pk_..."

It also warms the path. The browser address-finder SDK calls /connect the first time a user interacts with the field, warming the worker and TLS connection so the first real search lands on a hot path.

Keys are scoped per service

Each key is enabled for one or more of the three services — address, email and phone. A key that is not enabled for a service, or has that service disabled, returns 403 when it calls that endpoint. Create separate keys per service if you want to isolate usage and limits.

Locking a key to origins or IPs

A key can be restricted to specific origins (for browser use) or IP ranges (for server use) in the dashboard. A request from outside the allowed set returns 403. This is what makes a key safe to ship in client-side code: lock it to your domains and it is useless anywhere else.

For a browser widget, always use an origin-locked key. For a server-to-server integration, prefer an IP-locked key and keep it out of any client bundle.

Keeping keys secret

Treat keys as secrets. Do not commit them to source control or embed them in a public client bundle unless the key is origin-locked to your domains. Rotate a key from the dashboard if you suspect it has leaked; the old value stops working immediately.

FAQ

What does a Postio API key look like?
A Postio API key is the string "pk_" followed by 32 hexadecimal characters. There is no live/test infix — you get one key format, and its permissions (which services, which origins or IPs) are configured in the dashboard.
Can I use a Postio API key in front-end JavaScript?
Yes, if the key is locked to your origins in the dashboard. An origin-locked key only works when the request comes from an allowed domain, so it is safe to ship in browser code. Never ship an unlocked key client-side.
Why am I getting a 403 when my key is valid?
A 403 means the key is valid but not permitted for this request: either the service is disabled for that key, or the request came from an origin or IP address that is not on the key’s allow-list. A 401, by contrast, means the key itself is missing or wrong.

Related