The Entire Mechanism in One Sentence
HTTP Basic Authentication sends a username and password, joined by a colon and Base64 encoded, inside an Authorization header on every request. That is the whole scheme, nothing more. It has been part of HTTP since the early 1990s, predates almost every other web auth method still in use, and despite its age it remains genuinely common: internal admin tools, staging environments, router and printer web interfaces, and plenty of machine to machine APIs still speak it. Because the mechanism is so small, testing it thoroughly with curl is a skill you can pick up in one sitting, and it stays useful for years afterward.
Before anything else, the framing that matters most: Base64 is an encoding, not an encryption, a distinction our Base64 guide covers in depth. Anyone who intercepts a Basic Auth header can reverse it back to the original username and password in one step. That single fact is why the HTTPS rule near the bottom of this page is not a suggestion.
Testing With curl's Built In -u Flag
The fastest path, and the one you should reach for first, is curl's own credential flag:
curl -u username:password https://api.example.com/endpointcurl builds the Base64 encoded Authorization header for you automatically, behind the scenes. A few variations that come up constantly in real debugging sessions:
- Keep the password out of shell history. Omit the password after the colon:
curl -u username https://api.example.com/endpointand curl will prompt you to type it interactively instead of recording it in your terminal history file. - See exactly what was sent and received. Add
-vfor verbose mode. This prints the full request headers, including the Authorization header curl generated, alongside the server's complete response headers. - Just the HTTP status code, nothing else.
curl -o /dev/null -s -w "%{http_code}\n" -u username:password https://api.example.com/endpointis the compact form useful in scripts and health checks.
Building the Header Yourself, Without -u
Understanding what -u is doing under the hood removes any mystery from the scheme entirely. The header curl builds is literally this format:
Authorization: Basic base64(username:password)You can construct that exact value by hand in three steps:
- Write out
username:passwordwith a single colon separating the two. Note that a username itself cannot contain a colon, but a password can; only the first colon in the string counts as the separator. - Base64 encode the whole string. On the command line:
echo -n 'admin:hunter2' | base64, which printsYWRtaW46aHVudGVyMg==. The-nflag onechois not optional here; without it, echo appends a trailing newline character that gets encoded along with your password and silently breaks the credential. - Send it as a raw header instead of using
-u:curl -H "Authorization: Basic YWRtaW46aHVudGVyMg==" https://api.example.com/endpoint
For a faster version of the same step, our Basic Auth generator takes a plain username and password and produces the ready to paste header value, and can decode an existing header value right back into its username and password, entirely inside your browser.
A genuinely useful debugging trick: whenever you have an existing
Authorization: Basicheader value from a log file, a support ticket, or a colleague's screenshot, decode it with our Base64 decoder to instantly see the exact username being sent. A large share of confusing 401 errors turn out to be a stale or misspelled username hiding in plain sight inside an encoded string nobody thought to check.
Working Through a 401
Basic Auth failures come from a genuinely short list of causes, and working through them in order usually finds the problem quickly.
- Wrong credentials, or none sent at all. Run the request with
-vand confirm an Authorization header is present in the outgoing request, then decode its value to double check it matches the username and password you intended. - Shell quoting eating special characters. A password containing
@, a colon, spaces, or unicode characters is a shell quoting problem far more often than a Basic Auth problem. Wrap the entire-uargument in single quotes, for example-u 'admin:p@ss:word!', and remember that only the very first colon in that string is treated as the username and password separator; anything after it, including more colons, belongs to the password. - A trailing newline from manual encoding. Building the header yourself with plain
echoinstead ofecho -nsilently appends a newline character to the encoded password. This is the textbook "it decodes correctly in my Base64 tool but curl still gets a 401" bug, and it is almost always this exact cause. - The server actually wants a different scheme. Bearer tokens and Digest authentication both return a 401 that looks identical to a Basic Auth failure at first glance. Check the
WWW-Authenticateresponse header, visible with-v, which names the scheme the server expects. - A redirect silently dropped the header. curl strips the Authorization header by default when a redirect crosses to a different host, a sensible security default that nonetheless causes confusing failures. Add
--location-trustedonly when you genuinely trust the redirect target to receive your credentials.
A Complete Debugging Session, Start to Finish
$ curl -v -u admin:wrongpass https://api.example.com/status
> Authorization: Basic YWRtaW46d3JvbmdwYXNz
< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: Basic realm="Admin Area"
$ echo -n 'YWRtaW46d3JvbmdwYXNz' | base64 -d
admin:wrongpass
# confirms exactly what was sent, and the password is visibly wrong
$ curl -v -u admin:correctpass https://api.example.com/status
> Authorization: Basic YWRtaW46Y29ycmVjdHBhc3M=
< HTTP/1.1 200 OKThat decode-what-was-actually-sent step in the middle is the single highest value habit in this entire workflow. It removes all guessing about whether the failure is a wrong password, a typo, or something else entirely.
The HTTPS Requirement, Stated Plainly
Because Basic Auth credentials are Base64 encoded rather than encrypted, and Base64 reverses instantly with a single command, sending them over plain http:// means your username and password travel in a form that is effectively cleartext to anyone positioned on the network path between client and server. The rules that follow from this are not optional:
- Only ever send Basic Auth credentials over HTTPS. The TLS layer is what actually protects them in transit; Base64 encoding on its own protects nothing. Our HTTPS and TLS explainer covers exactly what that layer is doing.
- Never embed credentials directly in the URL, as in
https://user:pass@host/path. That form leaks into server access logs, browser history, and the Referer header sent to any third party resource the page loads. - Prefer tokens or OAuth for anything user facing. Our OAuth explainer covers the alternative. Basic Auth is a good fit for internal tooling and machine to machine calls, not for consumer facing login flows.
- Treat the credentials themselves like passwords, because they are. Rotate them periodically and scope them narrowly; generate strong values with our password generator rather than reusing something memorable.
Frequently Asked Questions
My password is definitely correct in the browser but curl still rejects it. Why?
This is almost always shell escaping or a trailing newline from manual encoding, not an actually wrong password. Wrap the full -u value in single quotes if it contains special characters, and if you Base64 encoded it by hand, confirm you used echo -n rather than plain echo. Decoding the header value you are actually sending with our Base64 decoder shows you the truth immediately rather than leaving it to guesswork.
Is Basic Auth inherently insecure, should it just be avoided entirely?
Not over HTTPS. The Base64 encoding is transparent and reversible by anyone, but TLS encrypts the entire request, header included, before it ever leaves the client. The real insecurity is Basic Auth sent over plain HTTP, or credentials that leak through URLs and log files. Used correctly, over HTTPS, scoped to an appropriate use case, it remains a simple and perfectly reasonable choice.
How do I send the same Basic Auth credentials from Postman or from application code instead of curl?
It is the identical header underneath a different interface. Postman has a dedicated Authorization tab where you choose Basic and enter the username and password directly. Every HTTP client library in every language accepts either a built in helper for Basic Auth or a manually set Authorization header. Generate the header value once with our Basic Auth generator and reuse the exact same string anywhere you need it.
Can I test an endpoint that combines Basic Auth with an additional custom header?
Yes, curl flags stack freely. For example, Basic Auth alongside a custom API key header in the same request: curl -u username:password -H "X-API-Key: abc123" -v https://api.example.com/endpoint. The -v output confirms both headers went out exactly as intended.
What does the server actually store, is it my password in Base64 form?
It should not be, and a well built server never stores it that way. The server decodes the incoming Authorization header on arrival, then compares the plaintext password against a securely hashed value stored in its database, using an algorithm like bcrypt or Argon2, covered in our hashing guide. Base64 is purely a transport format between client and server for this one request; it is never an appropriate storage format for anything sensitive.
