Challenge–Response Model

## The framework HTTP has no built-in login page and no session. Instead RFC 9110 section 11 (which absorbed RFC 7235) defines a tiny, scheme-agnostic **authentication framework**: the server *challenges*, the client *responds with credentials*, and the server re-evaluates the request. Everything specific — how credentials are computed, whether they expire, whether they are a password or a token — lives in a pluggable **authentication scheme**. Four header fields carry the whole thing: - **WWW-Authenticate** — sent by an origin server on **401 Unauthorized**; one or more challenges. - **Authorization** — sent by the client; credentials for the origin server. - **Proxy-Authenticate** — sent by a proxy on **407 Proxy Authentication Required**. - **Proxy-Authorization** — sent by the client; credentials for the *next* proxy. ## Anatomy of a challenge A challenge is a scheme token followed by either a single opaque `token68` blob or a comma-separated list of `name=value` auth-params: `WWW-Authenticate: Basic realm="ops-console", charset="UTF-8"` The scheme name is **case-insensitive** (`bearer` equals `Bearer`), and so are parameter names. `realm` is the one parameter defined for all schemes: an opaque string naming a **protection space** so a user agent can cache and reuse the right credentials. The protection space is scoped to the origin (scheme + host + port) plus the realm value — credentials cached for one realm must not be sent to another. Realms are shown to humans in browser prompts, so they should be short and non-sensitive, never a stack trace or a username list. ## The response half The client re-sends the *same* request, now with `Authorization: <scheme> <credentials>`. There is no negotiation state kept on the server; a REST/API client typically hardcodes the scheme it uses. If the credentials are rejected, the server answers 401 again — a browser then re-prompts, which is why a loop of prompts usually means bad credentials rather than a broken flow. Because every request carries credentials, **transport security matters**: `Basic` credentials are base64, which is encoding not encryption, and bearer tokens are equally replayable. Send them over TLS only. ## Preemptive authentication Waiting for a 401 costs a round trip and, for non-idempotent requests, means uploading the body twice (or dancing with `Expect: 100-continue`). Most API clients therefore attach `Authorization` from the start. Browsers do the same after the first challenge: once they have credentials for a realm they send them preemptively to URIs at or below the challenged path. So in production the challenge is often visible only when something is wrong. ## 401 versus 403 This is the classic follow-up. **401** = *unauthenticated*: the request lacked usable credentials, and the response describes how to supply them. **403** = *authenticated but not permitted*, or the server refuses to say more; it carries no `WWW-Authenticate` because there is nothing useful to retry. Returning 403 for a missing token robs the client of the challenge; returning 401 for a permission failure invites clients into a retry loop. Some APIs deliberately return 404 instead of 403 to avoid confirming a resource exists — a defensible privacy choice, but a conscious one. ## Caching interaction A request with an `Authorization` header is user-specific, so a shared cache must not reuse its response for other users unless the response explicitly permits it (`public`, `s-maxage`, or `must-revalidate`). Forgetting this is how one user's data ends up served to another from a CDN. ## What breaks in practice - 401 sent **without** `WWW-Authenticate` — a spec violation; well-behaved clients (curl `--anyauth`, HTTP libraries, browsers) then have no idea which scheme to use and cannot prompt. - A challenge naming a scheme the client does not implement — the client must ignore that challenge and, if none is left, treat the response as an error. - Using 401 to mean "session expired" while the app actually uses cookies: the honest signal is still 401, but there is no HTTP-level challenge for cookie login, so teams send `WWW-Authenticate` with a real scheme or accept that the status alone is the contract.