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 requests to endpoints, websites, and most networking interfaces. While it doesn’t have a lot of the bells and whistles 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.

As such, 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 only be sent over the HTTPS protocol. 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 wherein a single flag needs to be used. As with almost every cURL command, there are the long and short version of the flag:

curl -u username:password https://example.com

For a longer version of the cURL command use “–user”:

curl --user username:password https://example.com

For those that 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://example.com

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 more 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 – add data payloads for specific methods such as POST or PUT.

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://example.com

Alternatively, you can use URL encoding for special characters:

curl -u username:pass%40word%21 https://example.com

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://api.example.com/endpoint

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://example.com

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://example.com