API Authentication Methods: API Keys, JWT, OAuth 2.0, and HMAC

An API key is a long random string — typically 128 or 256 bits of entropy — that the client includes in every request. When the server receives the request, it looks up the key in its database to identify the caller and check permissions.

API keys are opaque: they carry no information themselves. The server resolves all context (who this is, what they can do) from the database record associated with the key. This makes revocation trivial — just delete or deactivate the record — but it also means every request requires a database lookup.

Keys are typically sent in the Authorization: Bearer <key> header or a custom header like X-API-Key. Never put keys in URL query parameters — they end up in server logs, proxy caches, and browser history.

A JWT is a compact, self-contained token that encodes claims (key-value pairs of information) and includes a cryptographic signature. The three parts — header, payload, and signature — are Base64URL-encoded and joined with dots:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyXzEyMyJ9.signature

The signature is computed over the header and payload using either a shared secret (HMAC-SHA256 → HS256) or a private key (RSA or ECDSA → RS256/ES256). The server verifies the signature without touching a database. This is the key advantage of JWTs: stateless verification.

Common claims include sub (subject — usually user ID), exp (expiration), iat (issued at), and aud (audience). Always set exp — JWTs without expiration are long-lived tokens that can't be easily revoked.

JWTs are not encrypted by default — anyone who has the token can decode the payload. Never put sensitive secrets in JWT claims unless you use JWE (JSON Web Encryption). The signature only guarantees integrity, not confidentiality.

OAuth 2.0 is an authorization framework, not an authentication protocol. It lets users grant limited access to their data on one service to another service — without sharing their password. "Login with Google" is OAuth. Reading a user's GitHub repos from your app is OAuth.

The core flow (Authorization Code grant, the most common): the user is redirected to the authorization server (Google, GitHub, etc.), they approve the requested scopes, and your app receives an authorization code. Your backend exchanges the code for an access token (and optionally a refresh token). The access token is then used to call the resource server (API) on the user's behalf.

Access tokens are short-lived (often 1 hour). Refresh tokens let your app obtain new access tokens without re-prompting the user. Scopes limit what the access token can do (e.g., read:email vs repo:write).

OpenID Connect (OIDC) extends OAuth 2.0 for authentication — it adds an id_token (a JWT) that identifies the user. If you need both "who is this person" and "what can they access," OIDC is the standard.

HMAC request signing goes further than API keys. Instead of sending the key directly, the client uses the secret key to compute an HMAC over specific request components — the HTTP method, path, headers (like Date or Content-Type), and often the request body. The resulting signature is sent in the request; the secret key is never transmitted.

The server recomputes the HMAC with the same key and compares signatures. If they match, the request is authentic and unmodified. Including a timestamp in the signed content prevents replay attacks — a signature that's more than a few minutes old is rejected.

HMAC signing is used by AWS (Signature Version 4), Stripe webhook signatures, GitHub webhook signatures, and many payment gateways. It provides a higher security bar than API keys because a captured request can't be replayed or modified. However, it is significantly more complex to implement correctly.