API Security: Authentication Headers

What you'll learn

How a client proves who it is to a REST API — and how to pick the right mechanism for each kind of caller. HTTP already defines an authentication contract; the job is to use it well and know the cost of every deviation.

The HTTP authentication contract

HTTP has a built-in handshake. When a request lacks valid credentials, the server answers 401 Unauthorized with a WWW-Authenticate header naming the scheme; the client retries with an Authorization header. That's the whole model — and every deviation from it has a cost (caching, CORS, tooling).

# server → client
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"

# client → server
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Pick the scheme by who is calling

Don't ask "which auth is best?" — ask "who is the caller?" Each answer points at one mechanism:

Authorization: Bearer (JWT)

The RFC 6750 standard: an opaque token the server decodes and validates. Pair it with a short-lived JWT — validate the signature, the expiry, and the audience so a token minted for one service can't be replayed against another:

import jwt

decoded = jwt.decode(
    token, secret,
    algorithms=["HS256"],           # or RS256/ES256 with a public key
    audience="internal-api",        # reject tokens minted for another service
    options={"require": ["exp", "iat", "sub"]},
)

• Always over HTTPS, always validate the signature — never trust an unverified token.
• Check aud to stop cross-service replay; prefer asymmetric keys (RS256/ES256) so verifiers hold only a public key.
• Short expiry (15 min–1 h) bounds the blast radius of a leak — at the cost of refresh infrastructure.

Authorization: Basic

Base64 of username:password — encoded, not encrypted. Simple, and fine for internal tooling or local dev, but the credential is a long-lived password that's painful to rotate.

Authorization: Basic dXNlcjpwYXNzd29yZA==   # base64("user:password")

API keys: Authorization: ApiKey vs X-API-Key

Both carry a static key; the difference is where. Keeping it in the standard Authorization header (a custom scheme) is far cheaper than a custom header:

Authorization: ApiKey ak_live_abc123xyz     # custom SCHEME — standard header (Stripe, Twilio)
X-API-Key: ak_live_abc123xyz                # custom HEADER — infrastructure cost

• X-API-Key is not treated as private by caches — HTTP caching infrastructure doesn't know it's a credential.
• CORS must list it explicitly, and client libraries/tooling don't understand it natively — developers must read your docs instead of using a standard.
• Acceptable when a gateway owns it — AWS API Gateway uses X-API-Key natively and enforces it before your code runs. Otherwise, prefer the Authorization: ApiKey scheme.

Cookie-based sessions

For a browser, the browser is the credential store: it sends the session cookie automatically on same-origin requests. The security is entirely in the flags:

Set-Cookie: session=<token>; HttpOnly; Secure; SameSite=Strict; Path=/api; Max-Age=3600

• HttpOnly — invisible to document.cookie and every JS API, so XSS can't steal it.
• Secure — sent over HTTPS only.
• SameSite=Strict — never sent cross-origin, which kills CSRF.
• Max-Age — a real expiry the browser enforces.

Issuing static API keys safely

Generate with real entropy, hand the key out once, and store only its hash — exactly like a password:

import secrets

def generate_api_key() -> str:
    return "ak_live_" + secrets.token_urlsafe(32)   # 32+ bytes of entropy

# store only the HASH in the DB; look it up to authenticate, delete it to revoke.
# rate limits and scopes attach to that DB record.

HMAC signatures — verifying webhook senders

An inbound webhook has no session and no token you issued. Instead the sender and you share a secret; it signs the raw body with HMAC-SHA256 and sends the signature in a header. You recompute and compare — in constant time:

import hmac, hashlib

def verify_webhook(payload: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Parse the Authorization header safely

Most auth bugs are parsing bugs. HTTP headers are case-insensitive, and a token can contain characters you don't expect — so look up case-insensitively, split on the first space only, and reject malformed input distinctly from missing input:

auth = headers.get("authorization") or headers.get("Authorization")
if not auth:
    raise Unauthorized("missing Authorization header")      # 401, WWW-Authenticate
scheme, _, credential = auth.partition(" ")                # split on the FIRST space only
if not credential:
    raise Unauthorized("malformed Authorization header")    # distinct from missing
if scheme.lower() == "bearer":
    ...                                                   # case-insensitive scheme

How the platform does all three at once

On the platform, a single Lambda Authorizer sits in front of every API and accepts three credential types — then hands the service one clean identity:

Authorization: Bearer <jwt>   ┐
x-api-key: ak_live_…          ├─▶  Lambda Authorizer  ─▶  { org_id, username, auth_type }
x-signature: sha256=…  (HMAC) ┘     validate · resolve org      injected into requestContext

• One boundary, many schemes — browser JWTs, machine API keys, and n8n HMAC callbacks all authenticate at the same place; auth is mandatory, and a request with no valid credential gets a 401.
• Identity, resolved once — the authorizer turns whichever credential into an org_id + username, and every downstream query is scoped by that org (Parts 5 & 6).
• Least privilege — keys are hashed and revocable, JWTs are short-lived and audience-checked, HMAC secrets live in Secrets Manager (Part 2).

The org_id: derive it, don't trust it

Multi-tenant APIs need to know which organization a request belongs to — and it's tempting to let the client send it as an X-Org-Id header (or an org_id in the body). Don't. A client can set any value, so trusting it is a one-line tenant-isolation breach: change the header, read another org's data. The org id must come from the verified credential, resolved server-side by the authorizer:

# the authorizer derives org_id from the credential — never from a client header
if auth_type == "jwt":
    org_id = claims["app_metadata"]["org_id"]     # a signed JWT claim
elif auth_type == "api_key":
    org_id = api_key_row.org_id                     # the key's owner row in the DB
# → injected into requestContext.authorizer; the service reads it THERE, not from headers

A CLAUDE.md for API auth

# CLAUDE.md — Auth

## The rule
- Credentials go in the Authorization header. 401 + WWW-Authenticate on failure.
- Pick by caller: browser→cookie, service→Bearer JWT, 3rd-party→ApiKey, webhook→HMAC.

## Do
- JWT: HTTPS, verify signature + exp + audience; prefer RS256/ES256; keep it short-lived.
- API keys: 32+ bytes entropy, store the HASH only, revoke via DB, rate-limit per key.
- Cookies (browser only): HttpOnly + Secure + SameSite=Strict + Max-Age.
- Webhooks: HMAC-SHA256, verify with hmac.compare_digest (constant time), be idempotent.
- Parse headers case-insensitively; split on the FIRST space; reject malformed ≠ missing.

## Don't
- No Basic auth over plain HTTP. No secret behind X-API-Key when Authorization works.
- Never store plaintext keys. Never compare signatures with ==.