Authentication

Bearer tokens

The common case for an API. --oauth2-bearer (curl 7.73.0) builds the header for you, and a hand-written -H is identical on the wire.

curl --oauth2-bearer "$TOKEN" https://api.example.com/me
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me

Prefer reading the token from the environment or a file over pasting it inline. Anything on the command line lands in your shell history and in ps output while the process runs.

export TOKEN="$(cat ~/.config/ex/token)"
curl --oauth2-bearer "$TOKEN" https://api.example.com/me

# or keep it out of argv entirely
curl -H @<(printf 'Authorization: Bearer %s\n' "$TOKEN") https://ex.com/me

Basic auth with -u

-u user:password base64-encodes the pair into Authorization: Basic. Base64 is encoding, not encryption, so this is only safe over HTTPS.

curl -u ada:s3cret https://ex.com/admin
curl -u ada https://ex.com/admin           # prompts for the password
curl -u 'token:' https://ex.com/api        # empty password, keep the colon
curl -u ':' --negotiate https://ex.com/    # credentials from the SSO ticket

Omitting the :password half makes curl prompt on the terminal, which keeps the secret out of history. A password containing : is fine, only the first colon splits the pair.

Auth mechanisms

-u supplies the credentials, and these flags choose how they are presented. The default is Basic.

curl --digest -u ada:s3cret https://ex.com/private
curl --anyauth -u ada:s3cret https://ex.com/private
curl --aws-sigv4 'aws:amz:us-east-1:s3' \
     -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
     https://bucket.s3.amazonaws.com/key

--anyauth and --digest cost an extra request, because curl sends an unauthenticated probe first to read WWW-Authenticate. Do not use them in a hot loop when you already know the scheme.

.netrc

-n / --netrc reads credentials from ~/.netrc keyed by hostname, so the secret never appears in the command. --netrc-file <path> points at a different file, and --netrc-optional makes the file optional instead of required.

# ~/.netrc   chmod 600
machine api.example.com
  login ada
  password s3cret

machine git.example.com
  login token
  password ghp_xxxxxxxxxxxx

default
  login anonymous
  password ada@example.com

chmod 600 ~/.netrc
curl -n https://api.example.com/me
curl --netrc-file ./ci.netrc https://api.example.com/me

curl does not warn about loose permissions on .netrc, so set 600 yourself. The default block matches any host not listed above it, so put it last.

Auth and redirects

Credentials are not resent to a different host when curl follows a redirect. That is deliberate, since a redirect to an attacker-controlled host would otherwise leak your token.

curl -L -u ada:s3cret https://ex.com/old      # auth dropped cross host
curl --location-trusted -u ada:s3cret https://ex.com/old

--location-trusted sends your password to wherever the redirect points. Only use it against a host you control, and never against a URL a user supplied. Note the asymmetry: a token you set with -H is not protected by that rule, so a hand-written Authorization header does follow the redirect.

Client certificates

mTLS uses a certificate instead of a password. -E / --cert takes the cert, and --key the private key when it is in a separate file.

curl -E client.pem --key client.key https://mtls.example.com/
curl -E client.p12:pass --cert-type P12 https://mtls.example.com/
curl -E client.pem:keypass --cacert corp-ca.pem https://mtls.example.com/

A passphrase after : in -E is visible in ps, so prefer --pass fed from an environment variable, or an unencrypted key on a 600 file in CI.