What Basic Auth Does and Why You Need It
Basic authentication is a method that sends a username and password with every request to a web server or API. The server checks those credentials and either grants or denies access. It is one of the oldest and simplest ways to protect a resource — a file, a web page, an API endpoint — so that only people with the right username and password can reach it.
Basic auth works by encoding your username and password together into a single string, then including that string in the header of every HTTP request. The server decodes it, checks whether the credentials are correct, and responds accordingly. You will encounter basic auth when you log into a router's admin panel, when a script needs to pull data from a protected API, or when you set up password protection on a folder in a web server.
The key thing to understand is that basic auth is not find over an unencrypted connection. Anyone watching the network traffic can read your credentials. For that reason, basic auth should only be used over HTTPS (encrypted connections). If you are protecting something important, consider stronger authentication methods instead.
Key Takeaways
- Basic auth encodes your username and password into a single string using base64, then sends it with each request in the Authorization header.
- The format is always username:password encoded in base64, prefixed with the word "Basic" in the header.
- Basic auth only works securely over HTTPS because the credentials are easily decoded if sent over plain HTTP.
- Different tools — curl, Postman, web browsers, and programming languages — have different ways to send basic auth, but they all produce the same result.
- Basic auth credentials are sent with every single request, so the server does not need to manage sessions or cookies.
The Encoding Step: Converting Username and Password to Base64
Basic auth uses base64 encoding, which is a way to convert text into a standard format that HTTP headers can safely carry. Base64 is not encryption — it is just a different way to represent the same information. Anyone who sees the encoded string can decode it back to the original username and password in seconds.
To create the encoded string, you combine your username and password with a colon in between: username:password. Then you encode that entire string using base64. If your username is "admin" and your password is "secret123", the string before encoding is admin:secret123. After base64 encoding, it becomes YWRtaW46c2VjcmV0MTIz.
You can encode this yourself using an online base64 tool, a command-line utility, or code in whatever language you are using. On Linux or macOS, the command is straightforward: echo -n "admin:secret123" | base64. The -n flag tells echo not to add a newline at the end, which would break the encoding. On Windows, you can use PowerShell: [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("admin:secret123")).
Adding Basic Auth to an HTTP Request
Once you have the base64-encoded string, you add it to the Authorization header of your HTTP request. The format is always: Authorization: Basic [encoded-string]. The word "Basic" tells the server that you are using basic authentication, not some other method.
If you are using curl from the command line, you can use the -u flag and curl will handle the encoding for you: curl -u admin:secret123 https://example.com/api/data. Curl automatically encodes the credentials and adds the Authorization header. If you want to see what header curl is sending, add the -v flag for verbose output.
If you are building a request manually or in code, you construct the header yourself. In JavaScript using the Fetch API, it looks like this: fetch('https://example.com/api/data', { headers: { 'Authorization': 'Basic YWRtaW46c2VjcmV0MTIz' } }). In Python using the requests library, you can pass the credentials directly: requests.get('https://example.com/api/data', auth=('admin', 'secret123')) and the library handles the encoding.
Using Basic Auth in Different Tools and Languages
Different tools have different syntax, but they all produce the same result: a request with the Authorization header set correctly.
| Tool or Language | How to Send Basic Auth |
|---|---|
| curl (command line) | curl -u username:password https://example.com |
| Postman (API testing) | Go to the Authorization tab, select "Basic Auth", enter username and password |
| Python (requests library) | requests.get(url, auth=('username', 'password')) |
| JavaScript (Fetch API) | fetch(url, { headers: { 'Authorization': 'Basic ' + btoa('username:password') } }) |
| Web browser | Browser prompts for username and password; you enter them in the dialog box |
| PHP (cURL) | curl_setopt($ch, CURLOPT_USERPWD, "username:password"); |
When you use a tool that handles basic auth for you — like curl's -u flag or Python's requests library — you do not have to think about base64 encoding. The tool does it automatically. When you are writing code or making raw HTTP requests, you may need to encode it yourself or use a library function.
Setting Up Basic Auth on a Web Server
If you are the one protecting a resource with basic auth, you need to configure your web server to require credentials. The exact steps depend on which server you are running.
On Apache, you create a file called .htaccess in the directory you want to protect. Inside it, you specify that basic auth is required and point to a password file. The password file contains usernames and encrypted passwords. You create this file using the htpasswd command: htpasswd -c .htpasswd admin. The server will prompt you to enter a password for the user "admin", and it will store an encrypted version in the file.
On Nginx, you use the auth_basic directive in your server configuration file. You point it to a password file in the same format as Apache's. On Node.js, you typically check the Authorization header in middleware and compare the decoded credentials against a list of valid users. In Express.js, you might use a package like express-basic-auth to handle this automatically.
The key point is that the server stores passwords in an encrypted or hashed form, not in plain text. When a request comes in with basic auth credentials, the server decodes the Authorization header, hashes the password that was sent, and compares it to the stored hash. If they match, access is granted.
When Basic Auth Is the Right Choice
Basic auth is straightforward and works everywhere, but it is not the best choice for every situation. Use basic auth when you are protecting an internal tool, an API used by scripts or other services, or a low-security resource where the main goal is to keep casual traffic out.
Do not use basic auth for protecting user accounts on a public website. Websites should use session-based authentication with cookies, or modern token-based methods like OAuth or JWT. Basic auth sends credentials with every request, which increases the risk if a request is intercepted. Sessions and tokens can be revoked or expire, giving you more control.
Basic auth is also not suitable if you need to log users out, track who is accessing what, or implement fine-grained permissions. It is a binary choice: either the credentials are correct and access is granted, or they are not and access is denied. There is no middle ground.
Common Mistakes and How to Avoid Them
The most common mistake is using basic auth over HTTP instead of HTTPS. If your connection is not encrypted, anyone on the network can read the Authorization header and decode your credentials in seconds. Always use HTTPS when basic auth is involved.
Another mistake is storing passwords in plain text on the server. If someone gains access to your password file, they have every user's credentials. Always hash or encrypt passwords before storing them. Use a proper hashing algorithm like bcrypt or PBKDF2, not a straightforward encoding like base64.
A third mistake is hardcoding credentials into scripts or configuration files that get checked into version control. If your repository is ever made public or compromised, your credentials are exposed. Use environment variables or a secrets management system instead. In most programming languages, you can read credentials from environment variables at runtime without storing them in the code.
Frequently Asked Questions
Is basic auth the same as a password?
No. A password is what a user knows. Basic auth is a method for sending that password (along with a username) to a server with each request. Basic auth uses the password, but it is not the password itself.
Can I use basic auth without HTTPS?
Technically yes, but you should not. Basic auth credentials are easily decoded, so they must be sent over an encrypted connection. If you send them over plain HTTP, anyone watching the network can read them.
How do I change a basic auth password?
On Apache, use the htpasswd command again with the same username: htpasswd .htpasswd admin. It will prompt you for a new password and overwrite the old one. On other servers, the process depends on how passwords are stored — check your server's documentation.
What happens if someone sends the wrong credentials?
The server returns a 401 Unauthorized response. Most web browsers will show a login dialog and let the user try again. APIs and scripts will receive the 401 status code and can handle it however the developer chose — retry, log an error, or fail gracefully.
Can I use special characters in a basic auth password?
Yes, but they must be URL-encoded before base64 encoding if you are constructing the header manually. Most tools that handle basic auth for you will do this automatically. Special characters like colons, spaces, and ampersands can cause problems if not encoded properly.