Skip to content
AI Engineer Guide.

concept · basics · intermediate · concept 8 of 24

API keys & credentials

0 of 24 complete

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

Prefix lookup, hash check, one refusalInteractive

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

Step 1/5 · present
1 · GET /v1/orders · bearercall · Client → API
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.

  1. Generate keys from a cryptographically secure random source with enough entropy that guessing is infeasible.
  2. 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.
  3. Attach scope, owner, creation time and expiry to the key record, and check scope at every authorisation point.
  4. Support two active keys per client during rotation, with an overlap window and a deprecation notice.
  5. Log the key id and never the key, and alert on use from a new network or a sudden volume change.
  6. Provide immediate revocation that takes effect at the next request, and test it as part of the release.

Trade-offs

ChoiceGood forCostFails when
Long-lived keySimple client integrationA leak is permanent until noticedThe key is embedded in a distributed client
Short-lived key with refreshBounded exposureRefresh logic in every clientClients cannot store a refresh credential
Per-environment keysBlast radius containmentMore keys to manageTeams copy production keys into staging
Key in a headerStandard and easy to proxyAppears in logs and tracesLogging middleware records headers
Trade-off mapInteractive

Good for

Simple client integration

Cost

A leak is permanent until noticed

Fails when

The key is embedded in a distributed client

  1. The key is embedded in a distributed client
  2. Clients cannot store a refresh credential
  3. Teams copy production keys into staging
  4. 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