The following examples will go through how to use curl with authentication. For obvious reasons, public APIs do not require authentication but private APIs will require authentication using authorization headers with basic auth, a bearer token header using a JWT (Javascript Web Token) or some other API key, or with a public key X.509 certificate and corresponding private key.
Note that web pages generally do not require the user to log in just to view the web page. If they website is authenticated, it will likely provide a log in page on the form, so authenticating with curl to a web page isn’t a practical exercise. curl authentication is done when consuming an API, not visiting a website. If the API returns a 401 status code that means you are not authenticated.
curl authentication with a private key / curl client certificate
To authenticate with a private key and certificate using curl, you will need to provide the --key and --cert options to your request. The private key must be decrypted in plain text. The provided certificate must contain the corresponding public key. If you need to decode the certificate for an inspection you can use our Certificate Decoder.
Using curl with a client certificate can be achieved in a couple of ways. You can curl with a certificate and key in the same file or curl with a certificate and private key in separate files.
As an example, using a private key and its corresponding certificate to authenticate, run the following command:
curl -v -GET --key key.pem --cert cert.pem https://example.comWhere -v is verbose, -GET is a GET request, --key key.pem is the key file or path to the private key, --cert cert.pem is the certificate with the corresponding public key, all followed up by the URL you are sending the request to.
Alternatively, you may combine the private key (key.pem) and X509 certificate (cert.pem) into one file. Again, the private key must be decrypted. The -E flag will be used, replacing the –key and –cert options. Here is an example of using the -E flag to authenticate with curl using a private key and certificate in one file:
curl -v -GET -E key-and-cert.pem https://example.comWhen using either of these options you may run across the following error:
could not load PEM client certificate, OpenSSL error error:0909006C:PEM routines:get_name:no start line, (no key found, wrong pass phrase, or wrong file format?)
If you do, double check that both the certificate file and private key file are correct or if using the -E flag that both the private key and certificate are present in the file.
curl authentication with a bearer token JWT
To authenticate with a bearer token using curl, you will need to pass the token in the authorization headers after the key word “Bearer”. This example assumes you have already generated a JWT (JavaScript Web Token).
To pass the bearer token in the authorization header in your curl request, run the following command:
curl -H "Authorization: Bearer your_token" https://example.comWhere -H is the header option followed by the authorization header containing your JWT bearer token, followed by the URL you are sending your authenticated request to.
curl authentication with basic auth
To authenticate with basic auth using curl, you will need to provide the --user option with a user name and password separated by a colon. Basic auth is the default, so it is not necessary to use the basic auth header. Note that due to the colon delimiter, a colon is not supported in the username. If you choose to be explicit about using basic auth, use the --basic option, but it isn’t required.
As an example, using basic auth to authenticate with curl, run the following command:
curl --user username:password https://example.comWhere --user is followed by the username and password (colon delimited) with basic auth being the default, then followed by the URL you are sending the authenticated request to. Note that curl -u is shorthand for curl --user and can be used instead. While these examples use the longer hand version --user, if you encounter issues specifically with using an api key instead of a username and password combination, try using the -u option instead. -u has proven to be more reliable.
Basic auth with curl sends the credentials base64 encoded in plain text, so it is recommended to use an alternate approach including bearer tokens and X.509 authentication with a certificate and private key.
In addition, you may use the --anyauth option to test if the authentication is required first, and if it is, go ahead and send the credentials.
curl --anyauth --user username:password https://example.comcurl SSL details
To show SSL connection details with curl, include the -v or --verbose option, meaning verbose. This will display the curl SSL handshake, SSL certificate, and any SSL certificate problems the connection may have.
As you can see, using curl -v shows the SSL Handshake and SSL certificate details.
Conclusion
Let us know in the comments if you would like to see additional examples of curl authentication with private keys and certificates, bearer tokens and JWTs, or basic auth.
Leave a Reply