Getting started

Authentication

Two credential types, two jobs: secret API keys authenticate your servers, publishable tokens authenticate the browser widget. They are not interchangeable.

Secret API keys

All server-side endpoints (/v1/validate, /v1/autocomplete, /v1/usage) authenticate with a bearer token in the Authorization header:

Authorization: Bearer ak_live_nZ3f…

Keys are formatted ak_live_… or ak_test_…. They are created in the console (or during sign-up on the homepage), belong to one project, and can be named, revoked, and re-revealed:

Shown once. The full key appears exactly once at creation. Store it in your secret manager immediately.
Reveal. Keys created since the reveal feature shipped can be re-revealed in the console by the signed-in account owner. Older keys cannot be recovered; create a new one instead.
Revocation. Revoking a key takes effect within about a minute (authentication results are briefly cached at the edge). Archiving a project revokes its active keys.
Storage. GeoVerdict stores only a SHA-256 hash for authentication, plus an encrypted copy for the console reveal. Plaintext keys never appear in logs.

Never use secret keys in a browser.

The /v1 endpoints send permissive CORS headers, so a browser call with a secret key will technically work. Do not do it: anyone can read the key from your page source or network tab and spend your credits. Browser integrations must use publishable tokens.

Live vs test keys

Test traffic is separated, not free.

An ak_test_ key calls the same real providers, returns the same real results, and bills from the same credit balance as a live key. It is an environment rather than a discount: it keeps development traffic out of your live logs, can be revoked on its own, and carries a tighter best-effort 60-request/minute limit per credential.

Test mode is not a canned sandbox: submitted addresses still go to the configured providers. Use test credentials for development and automated checks, then switch to ak_live_ for production traffic.

Publishable widget tokens

The browser autocomplete endpoint (/v1/widget/autocomplete) authenticates with a publishable token, formatted gv_pk_live_… or gv_pk_test_…. Publishable tokens are designed to be visible in page source:

Each token belongs to one project and carries an exact HTTPS origin allowlist (for example https://shop.example; no wildcards, paths, or plain HTTP). Requests from any other origin are rejected before any provider is called.
A publishable token can call only the widget autocomplete endpoint. It cannot validate addresses, read usage, or touch your account.
All tokens have per-token and per-origin limits of 120 requests per minute. Test tokens also have a tighter best-effort 60-request/minute per-token limit. Both environments draw from the same account credit balance.
Tokens are created, origin-edited, and revoked from a project's Autocomplete widget panel in the console. Revoking a widget token never affects your server API keys.

Conversely, the widget endpoint rejects ak_… keys and console sessions. See the widget guide for setup.

Unauthenticated endpoints

Endpoint	Purpose
`GET /healthz`	Service status and active provider ids. Free.
`POST /demo/validate`	The homepage demo. It defaults to the Netherlands and honors a trailing ISO alpha-2 country code; displayed samples and cache hits bypass the cache-miss IP allowance. Not for production use.