Skip to content

Send Basic Auth credentials with cURL

Use cURL's user option to attach a username and password pair.

OUTPUT FORMATSHTMLJSONMarkdown

cURL handles the encoding and header construction for you, so you only need to supply the credentials in the expected format.

The basic syntax

Add the -u option followed by your login and password separated by a colon. cURL then creates the Authorization header automatically using Basic Authentication, with the pair Base64-encoded for transport. You do not need to build that header manually.

Protected module: code0001

When the login is accepted, the test endpoint returns a JSON confirmation showing authenticated status and the supplied user name.

Protected module: code0002

Quick checklist before you run the request:

  • Confirm the endpoint expects Basic Auth rather than a token or API key.
  • Use a colon only as the separator between username and password.
  • Avoid usernames that themselves contain a colon, because the format becomes ambiguous.
  • Keep the whole -u value quoted, especially when the password includes spaces or shell-special characters.

What you are actually sending

cURL is a command-line tool for moving data between a client and a server. It works across many protocols, including HTTP and FTP, and is frequently used to probe APIs, fetch files, and script network calls.

Basic Auth is an HTTP authentication method. The client places the word Basic, a space, and then a Base64-encoded username:password string in the Authorization header.

401 versus 403

401 Unauthorized: the server did not accept the credentials you sent. Recheck the username and password, and make sure the endpoint supports HTTP Basic Authentication.

403 Forbidden: the server accepted the credentials but refused access to that resource. Check that the account has permission for the endpoint, and whether the API asks for additional permissions or scope.

A useful distinction: 401 is about identity not being established, while 403 is about an established identity lacking permission.

Keeping credentials safer

Always use HTTPS. Base64 encoding is not encryption, so credentials sent over plain HTTP can be decoded by anyone who intercepts the traffic.

Do not type the password directly into the command line. It may be saved in shell history and can be visible to other users on the same machine while the command runs. Instead, read it from an environment variable.

Protected module: code0003

For repeated use, credentials can be stored in a netrc file with restricted permissions and loaded with the netrc option.

Protected module: code0005

An environment variable is safer than an inline password, but it is not full secret management: values can still surface through process information, debugging tools, or logs. Production applications and automated workflows should load credentials from a secrets manager where possible. Avoid hardcoding credentials in scripts or committing them to version control. For long-term production API access, API keys or Bearer tokens are usually easier to rotate and revoke than a shared username and password.

Error decision map
SymptomLikely meaningFirst checks
401 UnauthorizedCredentials were not authenticatedUsername, password, and endpoint support for Basic Auth
403 ForbiddenCredentials were authenticated but access was deniedAccount permission and any required scope

Based on the captured error descriptions; endpoint behaviour can vary by server.

Frequently asked questions

Why do I get 401 Unauthorized?

A 401 means the server did not accept the credentials. Recheck the username and password, and confirm the endpoint actually supports HTTP Basic Authentication.

Why do I get 403 Forbidden?

A 403 means the credentials were accepted but the account is not allowed to reach that resource. Check account permissions and whether the API needs extra permissions or scope.

How can I pass a password more safely?

Use HTTPS, because Basic Auth encodes rather than encrypts credentials. Keep passwords out of the command line by using an environment variable or a netrc file, and prefer a secrets manager, API keys, or Bearer tokens for production work.

curl {{HTTPBIN_BASE_URL}}/basic-auth/login/password \
   -u "login:password"
{
  "authenticated": true,
  "user": "login"
}
export MY_PASSWORD="your-password"
curl {{HTTPBIN_BASE_URL}}/basic-auth/login/password \
  -u "login:$MY_PASSWORD"
curl --netrc {{HTTPBIN_BASE_URL}}/basic-auth/login/password