Overview
Every API requires authentication. Master cURL authentication patterns to test any API — from simple API keys to complex OAuth2 flows with token refresh.
Why This Matters
- -API testing — most endpoints require auth to access
- -Automation — scripts need programmatic auth flows
- -Debugging — isolate auth issues from application logic
- -Security — understand proper credential handling
How It Works
Step 1: Bearer Token Authentication
# Most common API authentication
TOKEN="your-api-token"
curl -sS -H "Authorization: Bearer $TOKEN" \
https://api.example.com/users
Step 2: OAuth2 Authorization Code Flow
# Step 1: Get authorization code (browser redirect)
# https://auth.example.com/authorize?client_id=ID&redirect_uri=URI&response_type=code
# Step 2: Exchange code for token
TOKEN_RESPONSE=$(curl -sS -X POST https://auth.example.com/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=$AUTH_CODE" \
-d "client_id=$CLIENT_ID" \
-d "client_secret=$CLIENT_SECRET" \
-d "redirect_uri=$REDIRECT_URI")
ACCESS_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token')
REFRESH_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.refresh_token')
# Step 3: Use access token
curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.example.com/protected
# Step 4: Refresh when expired
NEW_TOKEN=$(curl -sS -X POST https://auth.example.com/token \
-d "grant_type=refresh_token" \
-d "refresh_token=$REFRESH_TOKEN" \
-d "client_id=$CLIENT_ID" | jq -r '.access_token')
Step 3: API Key Authentication
# As header (most common)
curl -sS -H "X-API-Key: $API_KEY" https://api.example.com/data
# As query parameter (less secure)
curl -sS "https://api.example.com/data?api_key=$API_KEY"
Step 4: Basic Authentication
# Using -u flag (encodes to Base64 automatically)
curl -sS -u "username:password" https://api.example.com/data
# Manual Base64 header
AUTH=$(echo -n "username:password" | base64)
curl -sS -H "Authorization: Basic $AUTH" https://api.example.com/data
Step 5: Cookie-Based Sessions
# Login and save cookies
curl -sS -c cookies.txt -X POST \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"pass"}' \
https://app.example.com/api/login
# Use cookies in subsequent requests
curl -sS -b cookies.txt https://app.example.com/api/dashboard
# Clean up
rm cookies.txtBest Practices
- -Store credentials in environment variables, never in scripts
- -Use
-u for Basic auth (handles encoding automatically) - -Save cookies to temp files with mktemp, delete after use
- -Implement token refresh logic for long-running scripts
- -Use
--fail-with-body to get error details on auth failure
Common Mistakes
- -Hardcoding tokens in scripts (committed to version control)
- -Sending credentials over HTTP (must be HTTPS)
- -Not handling token expiration in automated scripts
- -Using query parameter auth when header auth is available
- -Leaving cookie files on disk after script completes