How to authenticate using username and password in cURL

Basic authentication allows access to protected HTTP resources using a username and password pair encoded in a request header. Many legacy APIs, admin panels, and internal tools still rely on this scheme, so being able to send basic-authenticated requests from cURL is useful for testing, automation, and troubleshooting. Using a predictable command-line pattern keeps these interactions repeatable and easy to script.

Under HTTP Basic, the client concatenates the username and password as username:password, base64-encodes that string, and sends it in the Authorization: Basic header. When the server validates the credentials, it returns the requested resource; otherwise, it returns an error such as 401 Unauthorized and may include a WWW-Authenticate: Basic header describing the realm. cURL automates this header construction when the --user option is supplied.

Because base64 encoding does not encrypt credentials, transmitting a username and password over plain HTTP exposes them to interception and logging. Using HTTPS, restricting file permissions, and avoiding direct passwords in shell history reduce the risk of credential leakage. The examples below assume a POSIX-style shell, but cURL behaves similarly across platforms.

1. Open a terminal where cURL commands can be executed.

   $ echo "$SHELL"
   /bin/bash

2. Trigger a Basic authentication challenge by sending a request without credentials to the protected endpoint.

   $ curl --verbose "https://www.example.com/api/protected"
   ##### snipped #####
   > GET /api/protected HTTP/1.1
   > Host: www.example.com
   ##### snipped #####
   < HTTP/1.1 401 Unauthorized
   < WWW-Authenticate: Basic realm="example"
   ##### snipped #####

   HTTP Basic challenges typically appear as 401 Unauthorized responses containing a WWW-Authenticate: Basic header.

3. Send credentials with the request using the --user option and a username:password pair.

   $ curl --user "username:password" "https://www.example.com/api/protected"
   {
     "data": "sample response",
     "authenticated": true
   }

   Use HTTPS URLs when transmitting real credentials because base64 encoding in HTTP Basic does not provide encryption.

4. Inspect the outgoing request headers with --verbose to confirm that an Authorization: Basic header is present.

   $ curl --user "username:password" --verbose "https://www.example.com/api/protected"
   ##### snipped #####
   > GET /api/protected HTTP/1.1
   > Host: www.example.com
   > Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
   ##### snipped #####
   < HTTP/1.1 200 OK
   < Content-Type: application/json
   ##### snipped #####

   The base64 value after Authorization: Basic decodes to the original username:password pair.

5. Avoid placing the password directly in shell history by providing only the username and letting cURL prompt for the password interactively.

   $ curl --user "username" "https://www.example.com/api/protected"
   Enter host password for user 'username':
   {
     "data": "sample response",
     "authenticated": true
   }

   Interactive prompting keeps the password out of command history and reduces exposure in process listings.

6. Create a plain-text credentials file containing the username:password pair when non-interactive use is required.

   $ printf 'username:password\n' > .curl-credentials

   Storing credentials in a dedicated file simplifies reuse in scripts and cron jobs.

7. Restrict permissions on the credentials file so only the current user can read it.

   $ chmod 600 .curl-credentials

   Loose permissions on credential files allow other users on the same system to read the username and password.

8. Load credentials from the file during the request using command substitution with the --user option.

   $ curl --user "$(cat .curl-credentials)" "https://www.example.com/api/protected"
   {
     "data": "sample response",
     "authenticated": true
   }

   Reading credentials from a file prevents the username and password from appearing directly in the command line.

9. Securely remove the credentials file after use if long-term storage is unnecessary.

   $ shred --verbose --remove .curl-credentials
   shred: .curl-credentials: pass 1/3 (random)...
   shred: .curl-credentials: pass 2/3 (random)...
   shred: .curl-credentials: pass 3/3 (random)...
   shred: .curl-credentials: removed

   Leaving plain-text credentials on disk allows later recovery by users or tools with access to the filesystem.

10. Confirm successful basic authentication by checking the HTTP status code and response body for the expected content.

    $ curl --user "username:password" --verbose "https://www.example.com/api/protected"
    ##### snipped #####
    < HTTP/1.1 200 OK
    < Content-Type: application/json
    ##### snipped #####
    {
      "data": "sample response",
      "authenticated": true
    }

    Success signals include an HTTP status such as 200 OK or 204 No Content and the absence of 401 Unauthorized errors.