Why it matters
Keys are the simplest way to authenticate a machine, and the simplicity hides three failure modes: they leak through logs, repositories and client bundles; they are stored in plaintext so a read becomes a credential compromise; and they never expire, so a leak discovered a year later is still live. The work is making a key identifiable, revocable and short-lived without breaking the clients that use it.
Mental model
It is a hotel key card: possession grants access, the desk can cancel it, and the room number is not the secret. The analogy breaks because a card is physical and hard to duplicate, while a key can be copied perfectly and used from anywhere at once.
How it works
The key is prefix plus secret. Only the prefix is stored in clear; the secret is hashed. Every failure returns one shape, so the endpoint cannot be used to test whether a key exists.
Client
holds the key
API
verifies keys
Key store
hashes + scope
GET /v1/orders?state=open HTTP/1.1
Host: api.example
Authorization: Bearer sk_live_9f2c.Qm1x...
Accept: application/json
sk_live_9f2c is the public lookup prefix.
Qm1x... is the secret, sent only over TLS
and never written to a log.Step 1: present. Hover, tap or tab to any message to inspect its payload.
Figure. The key string is a public prefix plus a secret, so the server finds the row by prefix and never needs to store the secret: a constant-time hash comparison verifies it, scope decides the action, and a revoked key fails with the same 401 shape as an unknown one. Rotation works because two keys are valid at once.
What to notice. The failure is a key refused after revocation: the client kept using it because the replacement was never rolled out, so every request fails. Storage is a hash with a lookup prefix, and the secret is never logged. Key ids, the token and the timestamps are illustrative; rate limiting and per-IP anomaly scoring are omitted.
Text version
Sequence across Client, API (the gateway that authenticates) and Key store. Step 1, present: Client to API GET /v1/orders with Authorization Bearer sk_live_9f2c plus a secret; sk_live_9f2c is the public lookup prefix and the secret travels only over TLS. API to Key store a prefix lookup that returns one row with id key_7f3c, an argon2id secret_hash, scope orders:read, a future expires_at and revoked_at null; Key store to API that row. An in-process API row verifies the secret in constant time, checks expiry and scope, updates last_used_at and logs the key id but never the key. API to Client 200 with the orders and a request id. Step 2, revoked: Client to API the same request with the old key sk_live_2a71; API to Key store a prefix lookup returning revoked_at 2026-11-18T09:14:00Z; API to Client 401 Unauthorized with WWW-Authenticate Bearer error invalid_token and a problem+json body code invalid_api_key, identical in shape and timing to an unknown prefix. Step 3, rotate: Client to API a request with the still-valid current key while the new key sk_live_7b1d is also active; API to Client 200 with the same scope. Two live keys are what make rotation a non-event.
- Generate keys from a cryptographically secure random source with enough entropy that guessing is infeasible.
- Give each key a public prefix and store only a hash of the secret part, so lookup is fast and the database holds no usable credential.
- Attach scope, owner, creation time and expiry to the key record, and check scope at every authorisation point.
- Support two active keys per client during rotation, with an overlap window and a deprecation notice.
- Log the key id and never the key, and alert on use from a new network or a sudden volume change.
- Provide immediate revocation that takes effect at the next request, and test it as part of the release.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Long-lived key | Simple client integration | A leak is permanent until noticed | The key is embedded in a distributed client |
| Short-lived key with refresh | Bounded exposure | Refresh logic in every client | Clients cannot store a refresh credential |
| Per-environment keys | Blast radius containment | More keys to manage | Teams copy production keys into staging |
| Key in a header | Standard and easy to proxy | Appears in logs and traces | Logging middleware records headers |
Good for
Simple client integration
Cost
A leak is permanent until noticed
Fails when
The key is embedded in a distributed client
- The key is embedded in a distributed client
- Clients cannot store a refresh credential
- Teams copy production keys into staging
- Logging middleware records headers
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Long-lived key is good for Simple client integration, costs A leak is permanent until noticed, and fails when The key is embedded in a distributed client. Short-lived key with refresh is good for Bounded exposure, costs Refresh logic in every client, and fails when Clients cannot store a refresh credential. Per-environment keys is good for Blast radius containment, costs More keys to manage, and fails when Teams copy production keys into staging. Key in a header is good for Standard and easy to proxy, costs Appears in logs and traces, and fails when Logging middleware records headers
Failure modes
- Key in a client bundle. The credential ships to browsers and is extracted from the network tab. Debug: search built assets for the key prefix and fail the build if it appears.
- Plaintext storage. A read-only database leak hands an attacker working credentials. Debug: inspect the key table schema and confirm no column stores the secret.
- Rotation outage. The old key is revoked before clients pick up the new one and every request fails. Debug: rehearse rotation with both keys valid and measure the overlap window.
In production
Track key age, last-used time and usage per key, and alert on a key that is active but unused for a long period. Cap the number of keys per tenant and require an owner for each.
Common misconceptions
People think: Keys are secure because they are long random strings.
Actually: Length does not help if the key is stored in plaintext, logged in a header or shipped in a client bundle.
People think: Rotating keys is an operational nicety.
Actually: It is the only way to bound the damage of a leak, and it has to be rehearsed because it is an availability risk.
Interview angle
Cover generation, hashed storage with a lookup prefix, scope, rotation and revocation, then name the leak paths. Treat rotation as an availability problem. A long random string in an environment variable is the start of an answer, not the end.
Sources
- OWASP API Security Top 10 — broken authentication and unrestricted resource consumption.
- NIST SP 800-63B, Digital Identity Guidelines — authenticator entropy, storage and rotation guidance.