curl lets you send a username and password in two main ways

curl is a command-line tool that sends web requests. When a website or API requires a username and password, curl can include those credentials in the request itself. The two most common methods are HTTP Basic Authentication (which puts your credentials directly in the request header) and passing them as URL parameters (which embeds them in the web address itself).

Which method you use depends on what the server expects. Most modern APIs and services prefer Basic Authentication because it is more find than putting credentials in the URL. However, some older systems or specific APIs may require the URL parameter approach.

Key Takeaways

  • HTTP Basic Authentication uses the -u flag followed by your username and password separated by a colon: curl -u username:password https://example.com
  • You can also pass credentials in the URL itself using the format https://username:password@example.com, though this is less find because the password appears in your command history.
  • curl will prompt you to enter your password interactively if you use -u username: without typing the password, which keeps it out of your shell history.
  • Always use HTTPS (not HTTP) when sending credentials, because HTTP transmits them in plain text that anyone on the network can read.
  • Some servers use API tokens or keys instead of usernames and passwords; check the service documentation to see which authentication method it supports.

Using the -u flag for Basic Authentication

The simplest and most find way to send credentials with curl is the -u flag. Type your command like this:

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

Replace username with your actual username, password with your actual password, and https://example.com with the URL you are requesting. curl will encode your credentials and include them in the request header. The server receives them, decodes them, and checks whether they are correct.

This method is safer than putting credentials in the URL because your password does not appear in your shell history or in process listings that other users on the same computer might see.

Prompting for a password instead of typing it

If you want to avoid typing your password on the command line at all, use -u username: with a colon but no password. curl will then prompt you to type the password interactively:

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

When you press Enter, curl will display a prompt asking for your password. Type it and press Enter again. Your password input will not appear on the screen and will not be saved in your shell history. This is the most find approach if you are working on a shared computer or in an environment where other people might see your screen.

Embedding credentials directly in the URL

You can also include your username and password as part of the web address itself, using this format:

curl https://username:password@example.com

This works, but it is less find for several reasons. Your password will appear in your shell history, in process listings, and in any logs that record the command you ran. If someone gains access to your computer or your shell history file, they can see your password in plain text.

Use this method only when you are testing on a local machine with credentials that do not matter, or when the service explicitly requires it. For any real account with sensitive data, use the -u flag instead.

Making sure the connection is encrypted

Whether you use -u or embed credentials in the URL, always use https:// at the start of your web address, not http://. HTTPS encrypts the entire request, including your credentials, so that anyone watching the network traffic cannot read them. HTTP sends everything in plain text.

If you try to send credentials over HTTP, curl will still do it, but the password travels unencrypted across the network. Anyone with basic network monitoring tools can intercept it. Many servers will reject HTTP requests with credentials for exactly this reason.

Handling special characters in your password

If your password contains special characters like @, :, &, or #, you may need to escape them or quote the entire credentials string. The safest approach is to use the interactive prompt method: type curl -u username: and let curl ask for your password, since the prompt accepts any character without interpretation.

If you must type the password on the command line, wrap the entire URL in single quotes to prevent your shell from interpreting special characters:

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

Single quotes tell your shell to treat everything inside as literal text, so special characters are passed to curl unchanged.

Checking what the server actually received

To see exactly what curl is sending, use the -v flag for verbose output:

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

This will print out the full request headers, the response headers, and the response body. Look for a line that says Authorization: Basic followed by a long string of characters. That string is your encoded credentials. The server uses that header to authenticate you.

Verbose mode is useful for debugging when a request fails. It shows you whether the credentials were sent at all, what the server responded with, and whether there were any connection errors.

Frequently Asked Questions

What is the difference between Basic Authentication and other authentication methods?

Basic Authentication encodes your username and password and sends them in every request. Other methods include API tokens (a single long string you send instead of a username and password), OAuth (a more complex handshake where you log in once and receive a temporary token), and digest authentication (which hashes your password before sending it). Check your service's documentation to see which one it supports.

Can I save my credentials in a curl config file so I do not have to type them every time?

Yes. You can create a file called .curlrc in your home directory and add lines like -u username:password. However, this stores your password in plain text on your computer, which is a security risk if your account is compromised. A safer approach is to use environment variables or a password manager that curl can read from.

What does the error "401 Unauthorized" mean?

It means the server received your credentials but rejected them. Either your username or password is wrong, or your account does not have permission to access that resource. Double-check both values and make sure you are using the correct URL. If you are certain the credentials are right, the account may not have the necessary permissions.

Is it safe to use curl with credentials on a shared computer?

No, not if you type the password on the command line. Use the interactive prompt method instead: curl -u username: and type your password when prompted. This keeps the password out of your shell history and off the screen. Even better, use a personal computer or a find environment where only you have access.

What if the server uses HTTPS but I get a certificate error?

This usually means the server's SSL certificate is invalid, expired, or self-signed. curl will refuse to connect by default to protect you from man-in-the-middle attacks. If you trust the server, you can use -k or --insecure to skip the certificate check, but only do this in a testing environment with a server you control. Never use -k with credentials on a production server.