Authentication

GoodVat authenticates server-to-server API requests with a single API key, passed as a Bearer token. This page covers how keys work, how they’re scoped to products, and how to send them correctly.

API key format

Keys look like this:

gv_live_7Kx2mPqR9sTvW4nJ8hL3bC6dF1gY0aZeXuN5oQiT

The prefix (gv_live_) identifies the environment the key belongs to, followed by 43 characters of cryptographically random entropy generated from a secure random source. Keys are stored server-side as a hash, never in plaintext — the raw key is shown to you exactly once, at creation time, in your Dashboard. If you lose it, you can’t retrieve it again; you’ll need to create a new one.

Creating a key

Create and manage keys from the API Keys page in your dashboard. Each key gets a human-readable name (e.g. "CI Pipeline Key") so you can tell them apart, and an optional expiry — set one if the key is for a short-lived job, or leave it non-expiring for long-running integrations.

Product access

A key automatically works for any product your organization is subscribed to. Subscribe to a product from the Products Dashboard, and requests authenticated with your org’s keys will succeed against that product’s endpoints immediately — no separate per-key setup required.

If your org isn’t subscribed to a product, requests to that product’s endpoints return 403 Forbidden, even with a valid key.

Sending the key

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer gv_live_7Kx2mPqR9sTvW4nJ8hL3bC6dF1gY0aZeXuN5oQiT

curl -X POST "https://api.goodvat.com/v1/address/normalize" \
  -H "Authorization: Bearer $GOODVAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "10 Downing Street, London SW1A 2AA, UK" }'

Common responses

Status	Meaning
`401 Unauthorized`	API key is present but invalid, expired, or revoked.
`403 Forbidden`	`Authorization` header missing or malformed, or the key is valid but your organization isn’t subscribed to the requested product.