Security · Lesson 08

API keys, JWTs & a hardening checklist

API keys are the simplest credential; JWTs are the most portable. Together they cover the majority of real-world API authentication — but both carry traps that are easy to walk into and expensive to clean up.

API keys: labelling the caller, not the person

Think of an API key like a vehicle registration plate. It tells you which vehicle is on the road (which application is calling), but says nothing about who is driving. API keys identify a client application or service account, not an individual human. That distinction matters: if you grant a key write access to your entire database, every user of that application — and every attacker who steals the key — has the same wide-open door.

Keys are best suited for: server-to-server calls where a service needs to identify itself; public-facing read-only APIs where you want usage tracking without user accounts; and simple integrations where OAuth would be engineering overkill.

JWTs: a signed statement about the caller

A JSON Web Token (JWT, pronounced "jot") is three Base64URL-encoded segments joined by dots: header.payload.signature. The server that issues it signs it; any server that holds the corresponding verification key can validate it without consulting a shared database. This is what makes JWTs useful for distributed systems.

Worked example: decoding a JWT

# A raw JWT (three dot-separated segments)
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzQyIiwibmFtZSI6IkFkYSBMb3ZlbGFjZSIsInJvbGUiOiJlZGl0b3IiLCJpYXQiOjE3NTAwMDAwMDAsImV4cCI6MTc1MDAwMzYwMH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

# Decoded header
{
  "alg": "HS256",   // signing algorithm
  "typ": "JWT"
}

# Decoded payload — signed, NOT encrypted; anyone can read this
{
  "sub":  "user_42",        // subject — who this token is about
  "name": "Ada Lovelace",   // custom claim
  "role": "editor",         // custom claim — used for authZ checks
  "iat":  1750000000,       // issued at (Unix timestamp)
  "exp":  1750003600        // expires in 1 hour — always set this
}

# Server verification pseudocode
header, payload, sig = jwt.split(".")
if not verify_signature(header, payload, sig, secret_key):
    return 401  # tampered or wrong key
if payload.exp < now():
    return 401  # expired
return payload  # trusted claims

JWT pitfalls

JWT's elegance hides several sharp edges that have caused real-world breaches:

1. The alg=none attack. Early JWT libraries accepted a token with "alg": "none" and no signature — effectively a self-signed "trust me" token. Fix: explicitly specify the expected algorithm; never accept none.
2. Payload is signed, not encrypted. Base64URL is reversible. Any secret in the payload — an email address, a role, PII — is readable by anyone who intercepts the token. For sensitive claims use JWE (JSON Web Encryption) or keep them out of the token entirely.
3. Hard to revoke. A valid token is accepted by any server until it expires. If you need to invalidate a token before expiry (user logs out, account suspended) you must maintain a block-list — which reintroduces state. Design for short expiry (15–60 min) to minimise the revocation window.
4. Missing or huge expiry. A token without an exp claim is valid forever. Set expiry; use refresh tokens for long-lived sessions.

Refresh strategy

Keep access tokens short-lived (15–60 minutes). Issue a longer-lived refresh token (hours to days, depending on risk tolerance) stored in an HttpOnly cookie. When the access token expires, the client silently exchanges the refresh token at the token endpoint for a new access token. If the refresh token is revoked (logout, security event), the session ends. This balances usability (no re-login) with security (short blast radius on a stolen access token).

API hardening checklist

The items below are not theoretical — each has been the root cause of a published API breach. Work through them as a pre-launch review or a periodic security audit.

Under the hood: how the signature is computed and verified

The word "signature" hides the whole mechanism. Here is exactly what happens. The signing input is the two encoded segments joined by a dot — base64url(header) + "." + base64url(payload) — call it the signing input. The algorithm in the header decides how that input becomes a signature.

HS256 (symmetric, HMAC-SHA256). Issuer and verifier share one secret:

That comparison is why tampering fails: flip a single character of the payload (say "role":"editor" → "admin") and the attacker can't produce a matching HMAC without the secret, so the recomputed signature won't equal theirs. The compare must be constant-time so timing can't leak how many bytes matched. The secret never travels in the token.

RS256 (asymmetric, RSA). The issuer signs with a private key; anyone verifies with the matching public key. This is the one that matters for distributed systems: a dozen services (or a third party) can verify your tokens with the public key while none of them can forge one, because forging needs the private key. With HS256 every verifier holds the secret — and any of them could mint tokens. Use RS256 (or ES256) the moment more than one party verifies.

Key rotation — kid and JWKS. The header carries a kid (key id). The verifier fetches the issuer's public keys from a JWKS endpoint (a JSON document of keys, e.g. /.well-known/jwks.json), looks up the key whose id matches kid, and verifies with it. That indirection lets the issuer roll keys: publish the new key, start signing with its kid, retire the old one once tokens expire — verifiers follow along automatically.

How to debug & inspect it

A JWT is not encrypted — it's three base64url chunks — so you can read it with nothing but a shell. (Decode to inspect; never paste a production token into a web tool.)

When verification fails, the symptom usually points straight at the cause:

Debug checklist: decode header + payload (above) → check exp/iat/nbf against the current time → confirm the server's pinned alg matches the header → verify the signature with the right key (by kid) → check for clock skew and a stray Bearer prefix.

In production: how leading APIs authenticate

Two approaches dominate real-world API authentication: the bearer key, where the secret itself is the credential, and the signed request, where a derived signature proves possession of the secret without transmitting it. Stripe and AWS represent the clearest public contrast between the two.

Deep dive: the simplicity–security trade-off between bearer keys and signed requests

Stripe's bearer-key model is easy to understand and easy to use: copy the key, put it in the header, done. The security model is: TLS protects the key in transit; treat the key like a password. This is sufficient for the vast majority of integrations — Stripe's developer experience reflects a deliberate choice to reduce friction over adding cryptographic complexity.

AWS SigV4 trades that simplicity for three additional properties. First, the secret is never transmitted — an attacker who captures network traffic (or a log of request headers) cannot reconstruct it. Second, the signature binds to the exact request: method, URL, headers, and body hash are all covered. A man-in-the-middle who intercepts a valid signed request cannot change even a single query parameter without breaking the signature. Third, the signing key is derived with a date and region baked in — a signature for us-east-1 on a Monday cannot be replayed to eu-west-1 on Tuesday.

The cost is implementation complexity: clients must correctly canonicalize the request, compute the HMAC chain, and handle clock skew (AWS rejects requests with a timestamp more than five minutes old). AWS provides SDKs that do this automatically, which is why most developers never implement SigV4 by hand.

For your own API design, the lesson is: bearer keys are the right default when TLS is reliable and the implementation surface is small; request signing is worth the complexity when secrets must never appear in logs, or when request integrity matters beyond transport-layer confidentiality. Webhooks (where you need to verify the payload came from the sender) often use HMAC signing for exactly this reason.

How leading APIs do it

Sources & further reading

• jwt.io — Introduction to JSON Web Tokens
• RFC 7519 — JSON Web Token (JWT)
• RFC 7518 — JSON Web Algorithms (JWA)
• OWASP API Security Project — Top 10
• OWASP JWT Cheat Sheet