APITesterThe command
curl -H "X-API-Key: $API_KEY" https://httpbin.org/headers
Opens the request console with this request filled in. It is sent from api-tester.com's server rather than from your machine, so it shows what the endpoint returns, not how your own network or curl build behaves.
Five places a credential can travel
| Task | How to send it |
|---|---|
| Username and password | -u user:password, which becomes an Authorization: Basic header. |
| OAuth or JWT access token | -H "Authorization: Bearer TOKEN", or --oauth2-bearer TOKEN. |
| API key | -H "X-API-Key: KEY", using whatever header name the API documents. |
| Session cookie | -b "session=VALUE", or a cookie jar with -b and -c. |
| Client certificate | --cert client.pem --key client-key.pem. |
Finding out what the API expects
When the documentation is unclear, the server will usually tell you. Make the request with no credentials and read the WWW-Authenticate header on the 401: it names the scheme, and sometimes a realm or the reason a token was refused. A 401 without that header generally means a custom scheme such as an API-key header, and only the documentation can name it.
curl -s -o /dev/null -D - https://httpbin.org/basic-auth/ada/s3cret | grep -i "^www-authenticate"
curl -s -o /dev/null -D - https://httpbin.org/bearer | grep -i "^www-authenticate"Storing the secret somewhere other than the command
A curl config file keeps a credential out of the command line altogether. Put the option in a file that only you can read and load it with -K; the file uses long option names without the leading dashes. If all you need is one header, -H @file reads it from a file instead (curl 7.55+). Either file can be written by a secret manager at deploy time and deleted afterwards.
# creds.conf (chmod 600)
# header = "X-API-Key: 3f9c1e-PLACEHOLDER"
curl -K creds.conf https://api.example.com/v1/orders
# one header line in a file
curl -H @auth-header.txt https://api.example.com/v1/ordersKeys in the URL, and what follows a redirect
Some APIs accept a key as a query parameter. It works, and the key is then written to the server's access log, to any proxy log on the way, and to your shell history as part of the URL. Prefer a header whenever the API offers both.
Redirects treat the mechanisms differently. Curl holds back -u credentials and an Authorization header when -L takes it to another host, but it cannot know that a header called X-API-Key is a secret, so that one is forwarded to wherever the redirect points.
curl -G https://httpbin.org/get --data-urlencode "api_key=$TOKEN" # works; the key is now in every log
curl -H "X-API-Key: $TOKEN" https://httpbin.org/get # same key, kept out of the URLCommon mistakes
- Verbose output contains the credential in full. Remove the authorization and cookie lines before pasting
-voutput into a ticket or a chat. - Send one kind of credential, not two. Some gateways answer
400to a request that carries both a token and a password instead of choosing between them. - All five forms are readable on plain
http://. None of them encrypts anything by itself; HTTPS does.
Related curl examples
Curl Basic Auth Example
-u takes a username and password and turns them into an Authorization: Basic header.
Curl Bearer Token Auth Header Example
A bearer token is a credential you present in a header; whoever holds it is treated as its owner.
Curl -u Flag Example
-u hands curl a username and a password.
Curl Send Cookies Example
Curl ignores cookies unless told otherwise.
All Curl Examples
49 worked examples, grouped by what you are trying to do.
More under Authentication
References
- curl man page: -K — Reading options, including credentials, from a config file.
- MDN: HTTP authentication — How servers ask for credentials and how clients answer.
These links leave api-tester.com, which is independent of the projects they point to.
FAQ
How do I send credentials with a curl request?
Use the form the API documents: -u user:password for Basic authentication, -H "Authorization: Bearer TOKEN" for a token, a header such as -H "X-API-Key: KEY" for an API key, or -b for a session cookie.
How do I pass an API key with curl?
Send it in the header the API names, for example curl -H "X-API-Key: YOUR_KEY" URL. Some APIs take it as a query parameter or as the username of Basic authentication instead.
How do I find out which authentication an API expects?
Make the request without credentials and read the WWW-Authenticate header on the 401 response. It names the scheme, such as Basic or Bearer.