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 [.inline-code]cURL[.inline-code], you can use the [.inline-code]-u[.inline-code] option flag (short for [.inline-code]--user[.inline-code]) as follows:

 $ curl -u username:password url

Where the [.inline-code]username[.inline-code] and the [.inline-code]password[.inline-code] are separated by a colon character ([.inline-code]:[.inline-code]).

Alternatively, if you only specify the [.inline-code]username[.inline-code], [.inline-code]cURL[.inline-code] will prompt you for a password:

 $ curl -u username url

[#insert-authorization]Using this command inserts an “Authorization” header under the hood[#insert-authorization]

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

 Authorization: Basic am9obmRvZTpwYXNzd29yZA==

[#recall-syntax]Remind yourself of the syntax using AI Command Search[#recall-syntax]

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

‍

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

[#escaping-special-chars]Escaping special characters in [.inline-code]curl[.inline-code] (such as your password)[#escaping-special-chars]

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 ([.inline-code]\[.inline-code]).

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

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

Here are some characters that should be escaped:

• Colon ([.inline-code]:[.inline-code]): the colon is used to separate the username and the password; note that this character shouldn't exist in your [.inline-code]username[.inline-code], and should be escaped if it exists in your [.inline-code]password[.inline-code].
• Ampersand ([.inline-code]&[.inline-code]): the ampersand is used by the shell to send a process to the background.
• Percent ([.inline-code]%[.inline-code]): 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]Use HTTPS (not HTTP) with your [.inline-code]curl[.inline-code] requests[#use-https]

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 [.inline-code]https[.inline-code] scheme in the target URL as follow:

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

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-curl-credentials]Secure your [.inline-code]curl[.inline-code] credentials in a [.inline-code].netrc[.inline-code] file[#secure-curl-credentials]

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. [.inline-code].bash_history[.inline-code] for Bash, [.inline-code].zsh_history[.inline-code] 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 [.inline-code]history[.inline-code] command:

 $ history -d entry_number

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

[#netrc]The .netrc file[#netrc]

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

 default
 login 
 password 

For example:

 default
 login john@example.com
 password h3lloJ0hn

And then use the [.inline-code]-n[.inline-code] option flag (short for [.inline-code]--netrc[.inline-code]) to perform an authentication:

 $ curl -n url

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

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

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

 $ chmod 600 ~/.netrc

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.