Authenticated Requests

Since your api key is embedded in the GET url format, this means if your urlbox url's are used publicly anyone could potentially start using your api key to make requests against the urlbox API and use up your quota.

To prevent anonymous usage, you can use the authenticated request format which is shown below:

Where:

  • api-key should be replaced by your urlbox API key which you can get by registering for an account.
  • format can be either:
    • png
    • jpg or jpeg
    • avif
    • webp
    • pdf
    • svg
    • html
  • auth-token should be replaced by a hash which is generated server side by taking the `HMAC SHA1` of the query string and signing it with your API Secret.
  • options should be replaced by a query string that contains all of the options you want to set.
    • e.g. url=example.com&full_page=true&width=300

Generating the auth token

No matter which language you are using, they will all have a method to generate a hmac-sha1 hash. We have code samples for the most popular languages available here.

A simple way to check that you have generated the correct token is to open your terminal and run the command:

echo -n <query string> | openssl sha1 -hmac "<YOUR SECRET KEY>"

Let's say we want to take a screenshot of urlbox.io and set the width option to 300px.

In order to generate the token, we take the query string, which is url=urlbox.io&width=300, and create the auth token by using our secret key to sign a hmac-sha1 hash of it:

echo -n "url=urlbox.io&width=300" | openssl sha1 -hmac "my_secret_key"
$> a6f5fb4b61eaba63a4546b87c14091c9ca3fbe73

We then insert this token into the url path to create our authenticated url:

Because the token is a hash of the query string, whenever you change your query string, you will need to ensure that the token matches, otherwise you will get an unauthenticated error response from the API.

Forcing authenticated requests

By default, unauthenticated requests are allowed when you first sign up, but you should switch over to authenticated requests as soon as you have gotten familiar with the API and it's options.

To force all requests to the API to use the authenticated format, you can go to the settings page in your dashboard and ensure that the Force Authenticated Requests option is enabled.

Now, if you try to make a request to the urlbox API without an auth token:

GET https://api.urlbox.io/v1/api-key/png?url=urlbox.io

you will receive the following response:

HTTP/2 400 Bad Request
Content-Type: application/json
X-Urlbox-Error-Message: Please enable tokenless requests in the dashboard or pass a valid auth token
{
"error": {
"message": "Please enable tokenless requests in the dashboard or pass a valid auth token",
"code": "TokenlessRequestsNotEnabled"
}
}
Was this page helpful?