cURL Auth Header Examples: Bearer Tokens, API Keys, Basic Auth
Practical cURL authentication examples for Bearer tokens, API keys, Basic Auth, and the mistakes that break requests.
Why auth examples are where cURL usually goes wrong
Most broken cURL commands are not broken because of HTTP itself. They fail because authentication details were copied with the wrong header name, quoted incorrectly for the active shell, or mixed with an API's custom requirements.
The good news is that most auth patterns reduce to a few repeatable shapes. Once you know those shapes, it becomes much easier to build requests, debug 401 and 403 responses, and hand commands off to teammates without confusion.
The three auth patterns you see most often
| Auth type | Typical transport | Most common mistake |
|---|---|---|
| Bearer token | Authorization header | Missing the Bearer prefix or copying an expired token |
| API key | Custom header or query parameter | Using the wrong header name or leaking the key into logs |
| Basic Auth | Authorization header with base64 credentials | Forgetting HTTPS or mixing it up with raw username/password headers |
Bearer token example
For modern APIs, Bearer tokens are often the default. The token goes into the Authorization header and is prefixed by the literal word Bearer followed by a space.
curl 'https://api.example.com/users' -H 'Authorization: Bearer eyJhbGciOi...'
If the API returns 401, first verify that the token is still valid, the required scope exists, and the header name is exactly Authorization. A surprisingly common failure is pasting only the token value and forgetting the prefix.
API key header example
API keys are not standardized the way Bearer tokens are. One service may expect X-API-Key, another may require api-key, and another may accept a query parameter instead. Always copy the exact contract from the service docs.
curl 'https://api.example.com/data' -H 'X-API-Key: sk_live_abc123'
Query-parameter API keys are still used in some systems, but they are easier to leak into logs, browser history, analytics, and screenshots. If the provider supports header-based transport, that is usually the safer default.
Basic Auth example
cURL can generate the Basic Auth header for you with the -u flag. That is cleaner than manually building the base64 string and less error-prone during quick tests.
curl 'https://api.example.com/admin' -u 'alice:correct-horse-battery-staple'
Basic Auth should be treated as transport-safe only when combined with HTTPS. Without TLS, the credentials can be recovered easily from the wire because Base64 is encoding, not encryption.
Adding auth to POST requests with JSON bodies
curl -X POST 'https://api.example.com/orders' -H 'Authorization: Bearer eyJhbGciOi...' -H 'Content-Type: application/json' --data-raw '{"sku":"book-1","qty":2}'
When auth and request bodies are both involved, many debugging sessions go sideways because the auth was correct but the content type or JSON payload was not. A working token does not guarantee a working business request.
The 401 vs 403 debugging shortcut
Common mistakes that waste the most time
The token may be valid, but the server will ignore it if the provider expects a different custom header.
Single quotes, double quotes, and variable interpolation differ across bash, zsh, PowerShell, and Windows cmd.
Some provider docs show placeholder prefixes or shortened example keys that are not valid real credentials.
A staging token often fails against production endpoints and vice versa.
Running commands with live keys can leave secrets in shell history, screenshots, tickets, and shared terminals.
Safe habits for sharing authenticated cURL commands
- Replace live secrets with placeholders before putting commands into docs, tickets, or chat.
- Keep the real header structure so the example remains mechanically useful to the next person.
- Explain what the request proves such as “tests token scope” or “creates a draft order” so readers know the intent.
- Prefer short-lived credentials when you must test manually in shared or recorded environments.
- Rotate anything exposed accidentally in screenshots, support logs, or terminal recordings.