Skip to content

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

Token lifecycle — issue once, present on every request, verify by store lookup; expiry and revocation are what make it safe

Editable source: docs/diagrams/token-lifecycle.drawio

On the wire:

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_9f3c8d2ab1e04f6c7a5b

Token generation rules

A token is only as strong as its entropy. Requirements:

  • Generated by a CSPRNG — secrets (Python), SecureRandom (Java), crypto.randomBytes (Node). Never random, 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 hashlib, secrets

def issue_api_key() -> tuple[str, str]:
    token = "sk_live_" + secrets.token_urlsafe(32)   # 256 bits entropy
    digest = hashlib.sha256(token.encode()).hexdigest()
    return token, digest   # return token once; store only digest
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);
    }
}
curl -H "Authorization: Bearer sk_live_9f3c8d2ab1e04f6c7a5b" \
     https://api.example.com/api/resource

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