Learn how to send authenticated requests
Since your API key is embedded in the
GET URL format, this means that if your Urlbox URLs 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:
api-key is replaced by your Urlbox API key, which you can get by registering for an account
auth-token is replaced by a hash, which is generated server side by taking the
HMAC SHA256of the query string and signing it with your API secret
format is one of:
options is replaced by a query string that contains all of the options you want to set - for example:
No matter which language you are using, they will all have a method to generate a hmac-sha256 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 following command:
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-sha256 hash of it:
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.
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.
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 its options.
Now, if you try to make a request to the urlbox API without an auth token:
you will receive the following response: