Curl With Basic Auth

Basic Access Authentication is an HTTP authentication scheme, which consists in a client providing a username and a password when making a request to a server, to prove who they claim to be in order to access protected resources. Note that performing Basic Access Authentication with cURL differs from the idea of authorization in the sense that the latter is performed by the server in order to determine users' access rights - i.e. authorization is what happens after authentication.

The short answer

To perform Basic Access Authentication with cURL, you can use the -u option flag (short for --user) as follows:

 $ curl -u username:password url

Run in Warp

Where the username and the password are separated by a colon character (:).

Alternatively, if you only specify the username, cURL will prompt you for a password:

 $ curl -u username url

Run in Warp

Using this command inserts an “Authorization” header under the hood

cURL will encode the username:password string using the Base64URL encoding scheme and include this value in the Basic authorization header of the HTTP request. For example, the johndoe:password string will be converted by cURL into the following HTTP header:

 Authorization: Basic am9obmRvZTpwYXNzd29yZA==

Run in Warp

Remind yourself of the syntax using AI Command Search

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Search feature:

‍

Entering basic authentication curl in the AI Command Search prompt results in exactly curl -u username:password url, which you can then quickly insert into your shell by doing CMD+ENTER.

Escaping special characters in curl (such as your password)

When using cURL for authentication, you may need to escape certain characters in your username or password.

To escape special characters, you can either use a backslash character (\).

 $ curl -u johndoe:h\&llo https://example.com

Run in Warp

Or you can wrap your string in single quotes, which will cause all special characters to lose their meaning and prevent the shell from performing expansions.

 $ curl -u johndoe:'h&llo' https://example.com

Run in Warp

Here are some characters that should be escaped:

• Colon (:): the colon is used to separate the username and the password; note that this character shouldn't exist in your username, and should be escaped if it exists in your password.
• Ampersand (&): the ampersand is used by the shell to send a process to the background.
• Percent (%): the percent sign is used to encode special characters in URLs, which may cause encoding errors.
• Space: the space character is used by the shell to separate command-line arguments and options.

Use HTTPS (not HTTP) with your curl requests

Generally speaking, it is never a good idea to pass your credentials in clear text over the network using an unsecured protocol such as HTTP.

When available, you should always use the HTTPS endpoint of the service you are trying to authenticate to, by specifying the https scheme in the target URL as follow:

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

Run in Warp

This will add a strong layer of encryption on top of HTTP that guarantees that your credentials are safe even if they were to fall into the wrong hands.

Secure your curl credentials in a .netrc file

In general, performing an authentication by typing your credentials in clear text in the command-line constitutes a significant security risk.

The reason for that lies in the fact that, just like your browser saves the searches you perform, the shell keeps an internal history list of all the commands you run.

These commands are temporarily stored in the RAM until you log out of your current shell session, which will cause the history list to be physically written to the disk in a file located in your home directory (e.g. .bash_history for Bash, .zsh_history for ZSH, etc).

Because of that, other users registered on the system might be able to access this file and steal your credentials.

You can of course clear specific entries of the history before it is written to the disk using the history command:

 $ history -d entry_number

Run in Warp

However, a better way to secure your credentials is to retrieve them from a file only you can access.

The .netrc file

In order to avoid passing your credentials in clear text to the cURL command, you can store them in a file named .netrc located in your home directory:

 default
 login 
 password 

Run in Warp

For example:

 default
 login [email protected]
 password h3lloJ0hn

Run in Warp

And then use the -n option flag (short for --netrc) to perform an authentication:

 $ curl -n url

Run in Warp

Note that if you want to keep this file in another directory, you can use the --netrc-file option flag instead to specificity its path:

 $ curl --netrc-file path/to/file url

Run in Warp

For obvious security reasons, this file should only be readable and writable by you, which can be achieved using the following chmod command:

 $ chmod 600 ~/.netrc

Run in Warp

You can learn more about changing the access rights and ownership of files on Linux by reading our articles on the chmod command and the chown command.