How to use HTTP Basic authentication in cURL

HTTP Basic authentication still appears on internal APIs, admin tools, lab systems, and compatibility endpoints where a fixed username and password gates a small set of requests. A predictable curl workflow keeps smoke tests, incident checks, and scripted validation runs easy to repeat when those endpoints do not use browser-based login flows.

A protected server normally answers an unauthenticated request with 401 Unauthorized and a WWW-Authenticate: Basic challenge. Passing --user gives curl the credential pair it needs to build the Authorization: Basic header, and the examples below use a masked service account plus a redacted secret placeholder to show the pattern without exposing a live identity. curl uses Basic as the default HTTP auth method unless another auth scheme is explicitly selected.

Basic credentials are only base64-encoded, not encrypted, so transport security and secret handling matter as much as the command syntax. Use HTTPS, keep verbose traces local, and prefer an interactive password prompt or a dedicated credential file when the password should not sit in shell history or copied command snippets.

1. Probe the endpoint without credentials so the 401 Unauthorized response and WWW-Authenticate: Basic challenge are visible before sending a password.

   $ curl --silent --show-error --include https://ops-api.example.com/v1/health
   HTTP/2 401
   server: envoy
   content-type: application/json
   www-authenticate: Basic realm="Operations Health API"
   x-request-id: 7f9d3d77d8a24c78
   
   {"error":"authentication required"}

   Replace the masked endpoint, account name, and redacted secret placeholder with the values used by the target service.

2. Send the request with --user and the username:password pair to satisfy the Basic challenge.

   $ curl --silent --show-error --user "svc-health-readonly:REDACTED_BASIC_AUTH_PASSWORD" https://ops-api.example.com/v1/health
   {
     "service": "ops-api",
     "status": "ok",
     "authenticated_as": "svc-health-readonly"
   }

   curl uses Basic as the default HTTP auth method for --user, so --basic is only needed when another auth option or config would otherwise take precedence.

3. Add --fail and --write-out when the command needs an explicit success signal in scripts or runbooks.

   $ curl --silent --show-error --fail --user "svc-health-readonly:REDACTED_BASIC_AUTH_PASSWORD" --write-out "\nHTTP %{http_code}\n" https://ops-api.example.com/v1/health
   {
     "service": "ops-api",
     "status": "ok",
     "authenticated_as": "svc-health-readonly"
   }
   HTTP 200

   Combining the response body with an HTTP 200 trailer makes it easier to distinguish an auth success from a network or application failure in automation.

4. Inspect the outbound auth header with verbose mode when a server rejects credentials that look correct.

   $ curl --verbose --silent --user "svc-health-readonly:REDACTED_BASIC_AUTH_PASSWORD" https://ops-api.example.com/v1/health
   * Host ops-api.example.com:443 was resolved.
   ##### snipped #####
   * Server auth using Basic with user 'svc-health-readonly'
   > GET /v1/health HTTP/2
   > Host: ops-api.example.com
   > Authorization: Basic ***REDACTED_BASE64_CREDENTIALS***
   > Accept: */*
   ##### snipped #####
   < HTTP/2 200
   {
     "service": "ops-api",
     "status": "ok",
     "authenticated_as": "svc-health-readonly"
   }

   Verbose output exposes the encoded credential header, so keep traces local and redact or discard them before sharing.

   Related: View request headers in cURL

5. Omit the password from the command line when interactive entry is safer than leaving the secret in shell history.

   $ curl --silent --show-error --include --user "svc-health-readonly" https://ops-api.example.com/v1/health
   Enter host password for user 'svc-health-readonly':
   HTTP/2 200
   content-type: application/json
   x-request-id: 2eb7d163c14a4c6b
   
   {
     "service": "ops-api",
     "status": "ok",
     "authenticated_as": "svc-health-readonly"
   }

   Providing only the username makes curl prompt for the password, which keeps the secret out of the literal command line.

6. Deliberately test the failure path so 401 Unauthorized auth problems are not confused with TLS, DNS, or application errors.

   $ curl --silent --show-error --include --user "svc-health-readonly:REDACTED_WRONG_PASSWORD" https://ops-api.example.com/v1/health
   HTTP/2 401
   server: envoy
   content-type: application/json
   www-authenticate: Basic realm="Operations Health API"
   x-request-id: c9bc154c50c34011
   
   {"error":"authentication required"}

   A repeated 401 with the Basic challenge usually means the username, password, realm mapping, or upstream credential store is wrong rather than the curl syntax itself.