Token Authentication (API Keys & Bearer Tokens)¶
What it is¶
Token authentication replaces the user's password with an opaque token — a random string issued by the server that the client presents on each request. The token carries no information itself; the server validates it by looking it up in a store (database, cache, or identity provider).
Two common flavors:
| Flavor | Header | Semantics |
|---|---|---|
| API Key | X-API-Key: <key> |
Identifies a client application or project, usually long-lived |
| Bearer Token | Authorization: Bearer <token> |
Identifies an authenticated session/user, per RFC 6750 |
Bearer semantics
A bearer token is like cash: whoever bears (possesses) it can spend it. Possession is the authentication proof — there is no binding to the client beyond knowing the string.
How it works¶
Editable source: docs/diagrams/token-lifecycle.drawio
On the wire:
Token generation rules¶
A token is only as strong as its entropy. Requirements:
- Generated by a CSPRNG —
secrets(Python),SecureRandom(Java),crypto.randomBytes(Node). Neverrandom,Math.random, or timestamps. - At least 128 bits of entropy — commonly a 32-byte random value, then Base64URL or hex encoded (~43 or ~64 characters).
- Stored hashed at rest — store
SHA-256(token)in the database. A database leak then exposes hashes, not usable tokens. - Prefix for identifiability — e.g.
sk_live_,ghp_— lets you (and secret scanners like GitHub's push protection) recognize leaked keys.
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.HexFormat;
SecureRandom rng = new SecureRandom();
byte[] bytes = new byte[32]; // 256 bits entropy
rng.nextBytes(bytes);
String token = "sk_live_" + Base64.getUrlEncoder()
.withoutPadding()
.encodeToString(bytes);
String digest = HexFormat.of().formatHex(
MessageDigest.getInstance("SHA-256")
.digest(token.getBytes(UTF_8))); // store this only
Reference implementation¶
import hashlib
from fastapi import Depends, FastAPI, HTTPException, Security
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
app = FastAPI()
bearer = HTTPBearer()
# Stand-in for a database table of *hashed* tokens → client metadata
TOKEN_STORE = {"<sha256-hex>": {"client": "billing-svc",
"scopes": ["read"]}}
def authenticate(
creds: HTTPAuthorizationCredentials = Security(bearer),
):
digest = hashlib.sha256(creds.credentials.encode()).hexdigest()
record = TOKEN_STORE.get(digest)
if record is None:
raise HTTPException(401, "Invalid token")
return record
@app.get("/api/resource")
def resource(client: dict = Depends(authenticate)):
return {"client": client["client"]}
@Component
public class ApiKeyFilter extends OncePerRequestFilter {
private final ApiKeyRepository repo; // hashed keys → client metadata
@Override
protected void doFilterInternal(HttpServletRequest req,
HttpServletResponse res,
FilterChain chain)
throws ServletException, IOException {
String header = req.getHeader("Authorization");
if (header != null && header.startsWith("Bearer ")) {
String digest = sha256(header.substring(7));
repo.findByDigest(digest).ifPresent(client ->
SecurityContextHolder.getContext().setAuthentication(
new ApiKeyAuthentication(client)));
}
chain.doFilter(req, res);
}
}
Strengths & weaknesses¶
| Strengths | Weaknesses |
|---|---|
| Simple for clients — set one header | Theft of a token = full access until revoked/expired |
| Password never leaves the auth step | Requires a lookup per request (DB/cache latency) |
| Easy rotation and revocation — delete a row | Long-lived keys accumulate; often forgotten |
| Attach metadata: scopes, rate limits, owner | No standard issuance flow — every API reinvents it |
| Cheap to validate (hash lookup vs. bcrypt) | API keys in URLs leak via logs, referrers, browser history |
Common attacks & mitigations¶
| Attack | Detail | Mitigation |
|---|---|---|
| Key leakage | Keys committed to git, logged in URLs, pasted in tickets | Prefix + secret scanning, header-only transport, pre-commit hooks |
| Token replay | A stolen bearer token works from anywhere | Short TTLs, optional sender-binding (mTLS, DPoP), IP allowlists for server keys |
| Brute force on the key | Feasible only if entropy is low | ≥128 bits CSPRNG output, rate limiting |
| Orphaned keys | Ex-employee/vendor keys still valid | Expiry dates, owner attribution, periodic audits, automated rotation |
| Timing attacks on lookup | token == stored comparisons or indexed plaintext lookups |
Hash first, lookup by hash index |
Never put tokens in query strings
?api_key=... ends up in server logs, proxy logs, browser history, and
Referer headers. Use headers — always.
When to use / avoid¶
Use it for
- Server-to-server integrations where a human isn't in the loop
- Partner/vendor API access with per-client rate limits and scopes
- Simple public APIs where OAuth would be overkill
Avoid it for
- End-user browser/mobile sessions (prefer OAuth or sessions)
- Scenarios needing fine-grained per-request identity proof
- Anything where you can't store/lookup tokens (use JWT instead)
Checklist¶
- Tokens generated with a CSPRNG, ≥128 bits entropy
- Stored hashed (SHA-256 minimum), never plaintext
- Transported in headers only — never URLs
- Expiry and owner metadata attached to every key
- Rotation procedure documented and ideally automated
- Scopes enforced server-side on every request