How to authenticate with a bearer token in cURL

Protected APIs accept bearer tokens as access credentials. cURL sends an existing access token in the Authorization: Bearer header to a protected API.

In cURL, --oauth2-bearer formats the standard Authorization: Bearer header for the request. The token must already be issued for the target API and have the permissions that its protected resource requires; sending the header does not obtain or renew a token.

Bearer tokens remain reusable secrets until they expire or are revoked. Anyone who obtains one may be able to use its permissions, so a real token belongs only on the intended provider's HTTPS endpoint. Public echo services return request details and must receive only fake demonstration tokens.

1. Set the URL to your provider's protected API endpoint.

   $ API_URL='https://api.example.com/v1/profile'

   api.example.com/v1/profile is a placeholder for the protected resource documented by your provider, not a working public test API.

2. Check the protected endpoint without an access token.

   $ curl --disable --silent --show-error \
     --write-out '\nHTTP %{http_code}\n' \
     "$API_URL"

   Example output:

   {
     "error": "unauthorized"
   }
   
   HTTP 401

   A 401 Unauthorized response shows that the request needs authentication. Response bodies vary by provider; a public resource that succeeds without a token cannot prove bearer authentication. --disable appears first so local curlrc defaults cannot add headers, redirects, or other options.

3. Read your existing access token into a variable in Bash without displaying it.

   $ read -r -s -p 'Access token: ' ACCESS_TOKEN

   The prompt accepts only the token string, without the Bearer prefix. Input is hidden and the token value is not typed into shell command history. An existing restricted secret source can supply the variable instead.
   Related: How to request and use a JWT with cURL

4. Inspect the bearer header with a fake token if header formatting needs troubleshooting.

   $ curl --disable --silent --show-error \
     --oauth2-bearer 'example-token-not-valid' \
     https://httpbin.org/headers
   {
     "headers": {
   ##### snipped #####
       "Authorization": "Bearer example-token-not-valid",
   ##### snipped #####
     }
   }

   This public service echoes request headers. The literal example-token-not-valid is fake; a real token or $ACCESS_TOKEN must never replace it here. Echoing a header verifies its format, not whether the provider accepts the credential.

   Related: How to view HTTP request headers with cURL

5. Send the protected request with your access token.

   $ curl --disable --silent --show-error \
     --oauth2-bearer "$ACCESS_TOKEN" \
     --write-out '\nHTTP %{http_code}\n' \
     "$API_URL"

   Example output:

   {
     "account": "example-user"
   }
   
   HTTP 200

   The provider's expected protected data and a successful HTTP status confirm the authenticated call. The response fields depend on the API. A 401 can mean an expired, invalid, or wrong-audience token; a 403 can indicate insufficient permissions.

   An inline real token in -H can be exposed through process listings. The equivalent request with -H @- reads the header from standard input instead, supplied by Bash's built-in printf:

   $ printf 'Authorization: Bearer %s\n' "$ACCESS_TOKEN" | \
     curl --disable --silent --show-error \
       -H @- \
       --write-out '\nHTTP %{http_code}\n' \
       "$API_URL"

   Both forms send the same bearer header. The inline spelling -H "Authorization: Bearer example-token-not-valid" is for fake demonstration tokens only. Uppercase -H means header; lowercase -h displays help. Hidden token input protects shell history, not expanded process arguments.

   Shared traces and debug output can expose the token. --location-trusted can forward credentials to another host; these requests do not follow redirects. If a batch is finished, unset ACCESS_TOKEN removes the variable from the current shell, but it does not revoke the token or erase saved logs.