How to send Basic Auth credentials using cURL?

cURL with Basic Auth: How to Pass a User and Password

If you work with the web, cURL is your command-line companion. It’s the essential tool for testing APIs, downloading content, and automating interactions with web services. A common task you’ll encounter is accessing a protected URL that requires a username and password. This is typically handled by HTTP Basic Authentication.

So, how do you use cURL with Basic Auth? You need to correctly provide the cURL user password credentials with your request. It’s straightforward, but knowing the right way can save you time and keep your credentials secure.

Let’s explore the best methods, from simple commands to more secure, script-friendly solutions.

---

How to Send Basic Auth Credentials with cURL

This section is designed to be easily captured as a Google Featured Snippet.

The simplest and most common way to send Basic Auth credentials with cURL is by using the -u or –user flag followed by your username:password.

Here are the steps:

1. Open your command line or terminal.
2. Use the -u flag and provide your credentials in the format “username:password”. It’s a good practice to enclose the credentials in double quotes to handle special characters in your password.
3. Append the URL you wish to access.

The command will look like this:

curl -u "your_username:your_password" https://api.example.com/data

cURL automatically encodes the credentials in Base64 and adds the necessary Authorization: Basic … header to the request.

---

The Best Method: Using the -u Flag (A curl basic auth example)

The -u flag is the idiomatic way to handle Basic Authentication in cURL. It’s clean, easy to remember, and does all the heavy lifting for you.

Let’s look at a practical curl basic auth example. Imagine you need to fetch a list of products from a protected API. Your username is api_user and your password is p@$$w0rd!.

Your command would be:

curl -u "api_user:p@$$w0rd!" https://api.store.com/v2/products

What happens behind the scenes? cURL takes the string api_user:p@$$w0rd!, encodes it, and sends it as an HTTP header like this: Authorization: Basic YXBpX3VzZXI6cEAJCdwMHJkIQ==. You don’t have to worry about any of that.

For Better Security: Prompt for the cURL Password

Hardcoding a password directly in the command line stores it in your shell’s history file (.bash_history, etc.), which is a security risk. For interactive use, a better approach is to let cURL prompt you for the password.

To do this, simply provide the username with the -u flag and omit the password:

curl -u "api_user" https://api.store.com/v2/products

cURL will then securely prompt you to enter the password, which will not be displayed on the screen or saved in your history.

Enter host password for user 'api_user':

This is the recommended method when you are manually running the command.

The Secure Way for Scripts: The .netrc File

When you need to automate a task that uses a curl user password, you should avoid placing credentials directly in your script. The professional solution is to use a .netrc file (or _netrc on Windows).

cURL automatically looks for this file in your home directory to find login credentials for a given website.

• Create the file: In your home directory (~), create a file named .netrc.

touch ~/.netrc

• Add your credentials: Add an entry for the website you want to access.

# Contents of ~/.netrc
machine api.store.com
login api_user
password p@$$w0rd!

• Set secure permissions: This is a critical step. Make the file readable only by you.

chmod 600 ~/.netrc

Now, you can run your cURL command without any authentication flags. cURL will find the credentials in .netrc and use them automatically.

# No username or password needed in the command!
curl https://api.store.com/v2/products

This method keeps your scripts clean and your passwords out of your code and command history.

The Manual Method: Building the Authorization Header

For a deeper understanding or in specific edge cases, you can construct the Authorization header yourself using the -H flag. This shows you what curl -u is doing for you.

• Base64 Encode: You need to encode your username:password string.

# On macOS or Linux
echo -n "api_user:p@$$w0rd!" | base64
# Output: YXBpX3VzZXI6cEAJCdwMHJkIQ==

• Construct the Header: Use the encoded string with the -H flag.

curl -H "Authorization: Basic YXBpX3VzZXI6cEAJCdwMHJkIQ==" https://api.store.com/v2/products

While this works, it’s cumbersome and prone to copy-paste errors. The -u flag is almost always the better choice.

Key Takeaways and Best Practices

To effectively use cURL with Basic Auth, remember these key points:

Method	Best For	Command Example
-u “user:pass”	Quick tests, simple requests	curl -u “user:pass” https://example.com
-u “user”	Interactive use (secure prompt)	curl -u “user” https://example.com
.netrc file	Scripts and automation (most secure)	curl https://example.com (after setup)
-H “Auth…”	Educational or specific edge cases	curl -H “Authorization: Basic…” https://…

Final Security Note: Basic Authentication is not encrypted, only encoded. Anyone intercepting the request can easily see your password. Therefore, only use Basic Auth over a secure HTTPS connection.