# Authentication

Every request carries an API Key:

```
Authorization: Bearer YOUR_API_KEY
```

API Keys are issued and revoked from the Portal. A key is shown once, in full, at the
moment it is created; after that the Portal displays only its masked prefix. If a key
is lost, revoke it and issue a new one — there is no way to see a full key again.

A request without a valid API Key is answered
[`401 invalid-key`](/errors/invalid-key). No Credits are consumed by a rejected
request.

## Keys and the Balance are separate questions

A valid API Key with an empty Balance still authenticates. The request is then refused
as [`402 insufficient-credits`](/errors/insufficient-credits) — a different error,
with a different fix. `401` means fix the key; `402` means add Credits.

`POST /v1/validate` requires only a valid API Key and works at a zero Balance, which
makes it the right probe for "is my key wired correctly" — it consumes nothing.

## Rotating a key

Rotation is self-service from the Portal. Press **Rotate key** on your dashboard: the
current key is retired, a new one is issued, and **the new key is shown once, in full,
at that moment** — copy it before you leave the page, because afterwards only its
masked prefix is displayed. The previous key stops working within the same window
described below.

Rotation changes nothing else about your Account: your Balance and your Tier are
untouched, and no Credits are consumed by rotating.

## Revocation takes effect within a minute

A revoked API Key can continue to authenticate for up to **~60 seconds** after
revocation — the gateway holds a short-lived key cache — and within a minute it stops
everywhere. If you are rotating credentials on a schedule, treat that minute as part
of the rotation window: issue the new key, move traffic, then revoke the old one.

### If calls must stop now

**The immediate cut-off is not key revocation.** If you need every call refused right
away — a leaked key in a running system, an integration you have lost control of — ask
us to **zero your Balance**. Contact us and we can do it.

With a zero Balance every Metered Call is refused
[`402 insufficient-credits`](/errors/insufficient-credits) on the request itself, with
no dependence on key-cache propagation. Your Ledger history is unaffected, and Credits
can be added again afterwards.

Revoke the key as well — zeroing the Balance stops the spending, and revoking the key
is what retires the credential.