How to Use cURL for Basic Authentication: A Complete Guide

cURL is a command-line tool that’s available by default in most operating systems. It’s intended to send various HTTP requests to endpoints, websites, and most networking interfaces. While it doesn’t offer many of the features of modern networking software, cURL can be deceptively powerful.

Additionally, cURL requests are highly modular and customizable. Ranging from sending basic GET requests to small-scale web scraping, cURL can be and is used for a wide variety of applications.

Authorization flags are also available in cURL. After all, many interfaces we interact with require at least basic authentication, such as a username or password.

What Is Basic Authentication?

As the name implies, Basic access authentication is a way to manage and present credentials for the HTTP protocol. Basic authentication, in simple terms, allows machines to send usernames and passwords to endpoints.

The process of basic authentication is quite simple. Credentials are stored in the HTTP header as Authorization: Basic <encoded-credentials>, wherein the username and password is converted into base64.

An important caveat is that the authorization header and basic authentication credentials should be sent only over HTTPS. Using the unsecured HTTP protocol can potentially leak credentials, which can lead to a whole host of issues.

How to Use Basic Auth in cURL

cURL Basic Auth Syntax

cURL’s basic authentication syntax is as simple as any other, requiring only a single flag. As with almost every cURL command, there are the long and short version of the flag:

curl -u username:password https://httpbin.org/basic-auth/user/passwd

For a longer version - use --user:

curl --user username:password https://httpbin.org/basic-auth/user/passwd

For those who want to be extra secure when sending a cURL request to an endpoint, avoid typing in the password. Your cURL command will look as such:

curl -u username https://httpbin.org/basic-auth/user/passwd

In most cases, sending such a cURL request will prompt you to enter the password. While less convenient, the password won’t appear in the system logs.

There are a few additional cURL commands you may want to include when sending your authorization request:

• -X. Allows you to specify the HTTP method (i.e,. GET, POST, PUT, etc.).
• -H. Allows you to specify HTTP headers (such as a user agent).
• -d. Adds data payloads for specific methods such as POST or PUT.

Common HTTP Authentication Response Codes

When you work with various protocols and APIs, understanding the server’s response is essential. If your basic auth credentials are incorrect or missing, the server will reject your HTTP request.

• 401 Unauthorized. It appears when you fail to send basic auth credentials or if the credentials provided are invalid. It essentially tells you to log in.
• 403 Forbidden. It means the server understands your credentials, but you still don't have permission to view the resource. Even valid basic authentication credentials won't help if your account lacks specific access rights.

To see these codes clearly, you can capture the status code using the -w (write-out) flag in your command line:

curl -o /dev/null -s -w "%{http_code}\n" -u user:passwd https://httpbin.org/basic-auth/user/passwd

Handling these errors programmatically is recommended. You can write scripts that check if the output is 200 (OK). If the output is 401, the script can prompt the user to check their basic auth credentials and try again.

Manual Header Construction

Sometimes you might need to manually construct the authorization header instead of using the -u flag. It's useful for debugging or when using tools that don't support the shortcut flags.

Combine your username and password into a single string separated by a colon (username:password) and encode it into Base64, ensuring you don’t include any trailing newline characters.

Once you have the encoded string, you can add it to your request using the -H flag:

curl -H "Authorization: Basic <Base64_String>" https://httpbin.org/basic-auth/user/passwd

It sends the exact same basic authentication credentials as the -u flag, but gives you more control over exactly how the header is built.

cURL Basic Authorization Password With Special Characters

Special characters (i.e., @, &, ^, :, etc.) could break the above basic auth commands as cURL would treat them differently than regular characters. There are two ways to solve the problem without ruining your authorization header.

First, you can use single quotes to indicate the beginning and end of the username:password string. Note that if your password or username uses single quotes (‘), this method will also break your authorization header, as cURL will read the beginning and end incorrectly:

curl -u 'username:password' https://httpbin.org/basic-auth/user/passwd

Alternatively, you can use URL encoding for special characters:

curl -u username:pass%40word%21 https://httpbin.org/basic-auth/user/passwd

Here’s URL encoding for most of the popular special characters:

cURL and Bearer Token Authentication

Bearer token authentication is considered a safer alternative to basic auth and is frequently used in various applications that have implemented OAuth. Tokens are acquired (sometimes only visible once) from a secure environment, can be easily revoked, read/write permissions, and can be refreshed quickly.

So, many APIs and modern applications will, in fact, use bearer tokens. Luckily, cURL supports both basic auth and bearer tokens:

curl -H "Authorization: Bearer <your-token>" https://jsonplaceholder.typicode.com/users

Troubleshooting 407 Authentication Required Error in cURL

You may get the 407 HTTP error when attempting to access a website or resource through a proxy server that requires authentication for itself.

To resolve the issue, you can use the verbose command (if the issue is not immediately visible) by attempting to send a regular GET request with the -v flag:

curl -v https://httpbin.org/basic-auth/user/passwd

If, for example, you need to add proxy authentication with cURL , use the -x flag to set your proxy server and the same -U for the proxy server credentials:

curl -x proxy.example.com:8080 -U proxy-username:proxy-password -u api-username:api-password https://httpbin.org/basic-auth/user/passwd

FAQ

curl -X POST -u username:password -d "param1=value1" https://jsonplaceholder.typicode.com/users