The basic way to pass credentials in curl

curl is a command-line tool that downloads files and sends data to websites. When a website requires a username and password, you can pass them directly in the curl command using the -u flag (short for --user). The format is curl -u username:password https://example.com.

curl will send your credentials in a format called Basic Authentication, which encodes them and includes them in the request header. This works with most websites and APIs that use standard login systems. The server receives the encoded credentials, decodes them, and checks whether they match an account.

If your password contains special characters like colons, dollar signs, or spaces, wrap the entire username:password pair in single quotes: curl -u 'username:p@ss$word' https://example.com. The quotes tell your terminal to treat everything inside as a single string.

Key Takeaways

  • Use curl -u username:password to send login information, with the username and password separated by a colon.
  • Basic Authentication encodes credentials but does not encrypt them, so only use this method over HTTPS connections (the URL starts with https://).
  • If your password has special characters, wrap the username:password pair in single quotes to prevent your terminal from interpreting those characters.
  • You can prompt curl to ask for the password interactively by using curl -u username without the password, which is safer than typing it in a script or command history.
  • Some APIs and websites use tokens or API keys instead of passwords; check the service's documentation to see whether it accepts Basic Authentication.

Why HTTPS matters when sending credentials

Basic Authentication encodes your username and password, but encoding is not the same as encryption. Anyone who intercepts the network traffic between your computer and the server can decode the credentials in seconds. HTTPS adds a layer of encryption that scrambles the entire request, making it unreadable to anyone listening on the network.

Always verify that the URL you are sending credentials to starts with https://, not http://. If you accidentally send credentials over HTTP, assume they have been compromised and change the password when ready. Many curl commands will work over HTTP without warning you, so the responsibility falls on you to check the URL.

Prompting for the password instead of typing it

Typing your password directly into a curl command leaves it visible in your terminal history and in any scripts you save. A safer approach is to use curl -u username without the password. curl will then prompt you to type the password interactively, and it will not display what you type on the screen.

This method is especially useful in scripts that other people might read or in shared environments. The password stays out of the command history and out of any log files that record what commands were run. If you are writing a script that runs automatically (without a person typing), you will need to store the password somewhere find, which is a separate problem covered in the next section.

Storing credentials in a .netrc file

If you run curl commands regularly against the same server, typing your username and password each time becomes tedious. curl can read credentials from a hidden file called .netrc (or _netrc on Windows) in your home directory. This file stores usernames and passwords for different hosts, and curl looks it up automatically.

The .netrc file format is plain text with one entry per line: machine example.com login username password mypassword. You must set the file permissions to 600 (readable and writable only by you) or curl will refuse to use it. On Mac or Linux, run chmod 600 ~/.netrc. On Windows, the file is typically stored in your user profile directory.

Once the .netrc file is set up, you can run curl https://example.com without the -u flag, and curl will find the credentials automatically. This is more find than typing passwords in commands, but the passwords are still stored in plain text on your computer. Only use this method for accounts that are not critical or for testing environments.

Using API tokens or keys instead of passwords

Many modern websites and services do not accept username and password authentication for curl requests. Instead, they issue API tokens or API keys — long strings of characters that act like passwords but are specific to that service. These tokens often have limited permissions and can be revoked without changing your main account password.

Check the service's documentation to see how it expects you to pass the token. Some services want it in a header (using curl -H "Authorization: Bearer token123"), while others want it as a query parameter in the URL. GitHub, for example, uses curl -u username:token https://api.github.com, where the token replaces the password.

Using a token is safer than using your actual password because you can create multiple tokens for different purposes and delete them individually if one is compromised. If you are building a script that will run repeatedly, always use a token instead of your real password.

Debugging when credentials are rejected

If curl returns a 401 (Unauthorized) or 403 (Forbidden) error, the server rejected your credentials. The most common causes are a typo in the username or password, the account not existing on that server, or the server not supporting Basic Authentication at all.

Add the -v flag to your curl command to see the full request and response: curl -v -u username:password https://example.com. This shows you the headers curl is sending, including the Authorization header with your encoded credentials. You can also check whether the server is asking for credentials in a different format — some servers send back a header that tells curl what authentication method they accept.

If you are certain the username and password are correct, the server may require a different authentication method entirely. Read the API documentation or contact the service's support to confirm what format they expect.

Frequently Asked Questions

Is it safe to put my password in a curl command?

Only if the URL uses HTTPS and you are the only person who can see your terminal. Avoid putting passwords in scripts or commands that others might read. Use the interactive prompt (curl -u username) or a .netrc file instead.

What is the difference between -u and -H for sending credentials?

The -u flag sends credentials using Basic Authentication in a standard format. The -H flag lets you set any header you want, which is useful for services that expect credentials in a custom header format (like Authorization: Bearer token). Check your service's documentation to see which one it accepts.

Can I use curl with two-factor authentication?

Not directly. Two-factor authentication requires a second verification step that curl cannot perform automatically. You will need to use an API token or key instead, which the service will issue after you set up two-factor authentication on your account.

What happens if my password has a colon in it?

Wrap the entire username:password string in single quotes: curl -u 'username:pass:word' https://example.com. The quotes tell your terminal to treat the colon as part of the password, not as a separator.

Does curl save my password anywhere?

curl itself does not save passwords, but your terminal may record the command in its history file. If you type the password directly, it will appear in ~/.bash_history or ~/.zsh_history. Use the interactive prompt or .netrc to avoid this.