Authentication

Key format

API keys are the string ulb_ followed by 48 hexadecimal characters. The prefix makes them recognisable in logs and secret scanners, which is the point — a key that looks like any other hex blob will eventually be committed to a repository without anyone noticing.

Sending the key

Both of these are accepted on every authenticated endpoint. Use whichever fits your HTTP client; there is no behavioural difference.

curl -H "x-api-key: $UNLOB_API_KEY" ...
curl -H "Authorization: Bearer $UNLOB_API_KEY" ...

How keys are stored

We store a cryptographic hash of each key and the last four characters, never the key itself. The plaintext is returned once, at creation, and cannot be recovered afterwards — by you or by us.

This means a compromised key listing cannot yield a working credential. It also means "I lost my key" is resolved by rotation rather than by retrieval.

Rotating and revoking

Rotation issues a replacement and retires the old key in a single transaction, so there is never a moment when your account has two live keys or none. Revocation is idempotent — revoking an already-revoked key succeeds rather than erroring, which makes cleanup scripts safe to re-run.

You can hold multiple keys on one account. A new key inherits the account plan, so issuing a per-environment key costs nothing and makes revocation surgical.

Which endpoints need a key

Everything except /healthz, /readyz, /metrics and /describe. /describe is deliberately open so an agent can discover the query surface before it holds a key — hardcoding a vendor vocabulary is how integrations break quietly.