Curl -u Flag Example

The command

curl -u ada:s3cret https://httpbin.org/basic-auth/ada/s3cret

Run this request in the API Tester

Opens the request console with this request filled in. It is sent from api-tester.com's server rather than from your machine, so it shows what the endpoint returns, not how your own network or curl build behaves.

The forms -u accepts

How curl reads the value

Curl splits the argument at the first colon and nowhere else. A username therefore cannot contain a colon, while a password may contain colons, at signs and anything else. The shell is a separate hazard: a dollar sign or an exclamation mark inside double quotes is rewritten before curl starts, so wrap any password you did not choose yourself in single quotes.

To check what was built from the value, ask for verbose output and look at the request line that starts with > authorization. It appears in lower case on HTTP/2.

# the password is everything after the first colon
curl -u 'ada:p@ss:w0rd' https://httpbin.org/basic-auth/ada/p%40ss%3Aw0rd

# show the header curl built
curl -s -o /dev/null -v -u ada:s3cret https://httpbin.org/basic-auth/ada/s3cret 2>&1 \
  | grep -i "^> authorization"

Scheme flags change what -u means

On its own, -u means HTTP Basic, sent with the very first request. Add --digest and the same two values are used differently: curl sends a first request without them, reads the challenge in the 401, and replies with a hash, so the password itself never travels. --ntlm and --negotiate work the same way with their own handshakes; for Kerberos the value is a bare colon, as in curl --negotiate -u : https://intranet.example.com/.

--anyauth lets curl ask the server which schemes it offers and choose the strongest. The price is an extra round trip on every command, which is why it suits exploration better than scripts.

curl --digest -u ada:s3cret https://httpbin.org/digest-auth/auth/ada/s3cret
curl --anyauth -u ada:s3cret https://httpbin.org/digest-auth/auth/ada/s3cret

Server credentials, proxy credentials and other protocols

Lower-case -u is always for the server named in the URL. A proxy that wants a login takes capital -U (--proxy-user), which travels in a different header; a 407 response is the proxy refusing you, a 401 is the destination. The flag is not limited to HTTP either: the same syntax logs in to FTP, SFTP, IMAP and SMTP servers.

curl -x http://proxy.example.com:3128 -U proxyuser:proxypass \
  -u ada:s3cret https://api.example.com/account

curl -u ada:s3cret ftp://ftp.example.com/reports/

Common mistakes

• Do not combine -u with your own Authorization header. When both are present curl sends the header you typed and silently drops the -u value.
• -u and -U are different options. Credentials sent to the wrong one are simply never seen by the party that wanted them.
• A value without a colon makes curl stop and prompt. In a cron job or a pipeline there is nobody to answer, so always include the colon in scripts.

Related curl examples

References

• curl man page: -u — The full description of --user.
• curl man page: --anyauth — Letting curl pick the authentication scheme.
• curl man page: --digest — Using Digest authentication with the same credentials.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ