Chapter 02 of 11
HTTP Basic Authentication and Digest, Explained
Why Base64 is not encryption, what Digest was designed to solve, where both still make sense, and the challenge-response mechanics behind them.
HTTP Basic authentication and HTTP Digest predate almost everything else in this guide. You should understand them because you will meet them, and because the reasons they lost are the reasons the newer schemes look the way they do.
Basic, and the Base64 misunderstanding
HTTP Basic, defined in RFC 7617, concatenates the username and password with a colon, encodes the result with Base64, and sends it in the Authorization header.
Authorization: Basic YWxpY2U6c3VwM3JzM2NyZXQ=Base64 is an encoding, not encryption. Decoding requires nothing but the standard library, and there is no key involved. The credential is effectively in plaintext, and TLS is the only thing protecting it.
That is not a reason to never use Basic. It is a reason to be precise about what it is, namely a way to put a username and password on a request. Over TLS, between two machines, with a generated secret instead of a human password, that is a perfectly reasonable arrangement. RFC 6749 specifies exactly this for client authentication at an OAuth token endpoint.
Where Basic is a poor fit is anything user-facing. It has no logout, because the browser keeps sending the credential. It has no expiry, because the credential is the password. And it offers no way to revoke one session, because there are no sessions.
Digest, and what it was solving
Digest, originally RFC 2617 and modernised in RFC 7616, was designed for a world where TLS was not universal. Its goal was to authenticate with a password without ever sending the password.
The exchange has two round trips.
1. GET /resource
→ 401 Unauthorized
WWW-Authenticate: Digest realm="api", qop="auth",
nonce="dcd98b7102dd2f0e", algorithm=SHA-256
2. GET /resource
Authorization: Digest username="alice", realm="api",
nonce="dcd98b7102dd2f0e", uri="/resource", qop=auth,
nc=00000001, cnonce="0a4f113b", response="6629fae4939..."The response value is a hash built from the username, the password, the realm, the server's nonce, the client's own nonce, a request counter and the method with the URI. The server computes the same hash and compares.
Three properties fall out of that construction.
The password never travels. An eavesdropper sees a hash that is useless for any other request.
Replay is bounded. The server nonce and the counter mean a captured response cannot be replayed indefinitely.
Part of the request is covered. With qop=auth-int the body is included too, so a proxy cannot alter it unnoticed.
What Digest costs
The properties above are real, and so are the trade-offs that made Digest lose.
| Cost | Why it matters |
|---|---|
| Two round trips | Every unauthenticated request is a 401 followed by a retry |
| Recoverable passwords on the server | The server needs the password or a realm-specific hash to verify, so it cannot store a modern one-way hash |
| Weak default algorithm | The original specification used MD5, and RFC 7616 added SHA-256 that not every implementation supports |
| Nonce state | The server has to track nonces and counters to make replay protection meaningful |
| No delegation | There is no way to give a third party limited access without giving them the password |
The second row is the decisive one. Storing passwords in a form the server can reverse or replay is the opposite of current practice, and once TLS became universal the whole point of not sending the password evaporated.
Where you still meet them
| Scheme | Where it turns up |
|---|---|
| Basic | Client authentication at OAuth token endpoints, internal service calls, CI credentials, plenty of vendor APIs |
| Digest | Embedded devices, cameras, printers, network equipment, some SIP deployments, older enterprise systems |
Neither is a good choice for a new public API, and both are common enough that a testing tool without them makes you write custom code for the one integration that needs it.
Practical guidance
If you use Basic, use a generated secret instead of a human password, put it behind TLS with no HTTP fallback, and give it the same rotation treatment an API key gets. Never accept it on a plain HTTP listener, even one that redirects, because the credential is already sent by then.
If you integrate with Digest, negotiate SHA-256 where the other side supports it, expect the extra round trip, and store the credential exactly as you would a password. Do not attempt to build Digest into a new API of your own, because everything it offers is available with less complexity from a token scheme over TLS.
In Routebase
Both schemes are in the catalogue and both configure the same way as everything else, which means at environment, suite, case or persona level.
Basic Auth takes a username and a password, and it sends them Base64-encoded in the Authorization header. Both fields accept {{VARIABLE}} placeholders, so the password lives in a secret variable and not in the configuration.
Digest Auth takes the username and password plus the algorithm, with MD5, MD5-sess, SHA-256 and SHA-256-sess available. The remaining Digest parameters are there when a server needs them set explicitly. Those cover the quality of protection, the nonce count, the client nonce and the opaque value, along with a switch to disable the automatic retry.
Because both live in the same catalogue as the token schemes, a suite that has to talk to one legacy service and one modern one uses suite-level or case-level overrides, not a second tool. See Project Auth for the configuration surface.
Frequently asked questions
Is HTTP Basic authentication secure?
It is exactly as secure as the connection underneath it and no more. Basic encodes the username and password with Base64, which is an encoding rather than encryption, so anyone who can read the request can read the credential. Over TLS that is acceptable for machine-to-machine calls, and over plain HTTP it is equivalent to sending the password in the clear.
What is the difference between Basic and Digest authentication?
Basic sends the password itself, encoded but not protected, on every request. Digest never sends the password, and instead answers a server challenge with a hash computed from the password, a server nonce and details of the request. Digest therefore survives an eavesdropper on a plain connection, at the cost of a second round trip and a server that must keep the password in a recoverable form.
Is Digest authentication still used?
It appears mainly in embedded devices, network equipment, older enterprise systems and some SIP deployments, where it was the standard answer before TLS was universal. RFC 7616 modernised it in 2015 with SHA-256, and new APIs still choose a token scheme instead. The reason to understand Digest is that you will have to integrate with something that speaks it.
When should you use Basic authentication for an API?
It suits machine-to-machine calls over TLS where the credential is a generated secret rather than a human password, and where the caller cannot easily manage a token flow. Client authentication at an OAuth token endpoint is the most common legitimate case, since RFC 6749 defines exactly that. Avoid it for anything user-facing, because it offers no logout, no expiry and no way to revoke one session.
Last reviewed by The Routebase Team.