Screenshot API Sign API Key

API Keys for Public-Facing Websites

If you want to display real-time or cached screenshots on a publicly accessible website, you'll need to sign your API key to ensure secure and authenticated access. This process is also known as hotlinking and can be done with Add Screenshots' Screenshot API.

To get started, you'll need to generate a secret key and API key in your Add Screenshots account. Once you have these keys, you can build a signed screen capture URL that includes a unique token signed by the secret key. This token ensures that only authorized requests are able to access the Screenshot API.

With the signed screen capture URL, you can embed real-time or cached screenshots on your website using an <img> tag. The screenshot will be dynamically generated and displayed on your website as a PNG or JPEG image.

By signing your API key, you can ensure the security and authenticity of your screenshots and prevent unauthorized access to your Add Screenshots account.

How do I use the Public and Secret Screenshot API key?

To use the API for public facing website, such as embedding hotlinks inside of your website, use the public key to authenticate your account and sign the URL with your secret key to create a base64 HMAC SHA256 signed token as shown below.

Screenshot API with a public token


Step by step guide to create a signed token

To sign a token, you need the following information:

  1. Your Secret API Key, found on the API Keys page
  2. The website URL and query string parameters to take a screenshot

Step 1 – Build the URL query string

First, let's build the URL to the website to take a screenshot of and the list of query string parameters.

In the following example, let's say we'd like to:

  1. Take a full-page screenshot (fullpage=true)
  2. Take the screenshot from the Australia East region (region=australia-east)
  3. Cache the screenshot for 1 day, which is 86400 seconds (ttl=86400)
  4. Take a screenshot of google.com.au (url=google.com.au)

The query string to sign is: fullpage=true&region=australia-east&ttl=86400&url=google.com.au

Step 2 – Sign the URL query string to get a token

Use the signed token languages section to programmatically sign a token.

The query string produced in the previous step must be signed with a HMAC SHA256 signature to produce a token to be included in the URL.

Your Secret API key is located on the API Keys page.


Step 3 – Combine the URL query string, public key and token

Combine everything to get the final URL that can be used on a public website as shown below:

Your Base64 encoded HMAC SHA256 token generated in the previous step.

Your Public API key is located on the API Keys page.


Notes:
  • A token must be generate for each URL and query string combination
  • The Public Key and Secret key only works for GET requests
  • POST requests can only be used with the Primary or Secondary API key

Programmatically create a base64 token using HMAC SHA256

In the following examples, replace the SECRET_API_KEY and QUERY_STRING with your own values.

Create a token in NodeJS

var crypto = require('crypto');
var token = crypto.createHmac('sha256', 'SECRET_API_KEY').update('QUERY_STRING').digest('base64');


Create a token in JavaScript

<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/hmac-sha256.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/enc-base64.min.js"></script>

<script>
var hash = CryptoJS.HmacSHA256("QUERY_STRING", "SECRET_API_KEY");
var token = CryptoJS.enc.Base64.stringify(hash);
document.write(token);
</script>


Generate a token in PowerShell

$urlQuery = 'QUERY_STRING'
$apiKey = 'SECRET_API_KEY'
$hmacsha = New-Object System.Security.Cryptography.HMACSHA256
$hmacsha.key = [Text.Encoding]::ASCII.GetBytes($apiKey)
$signature = $hmacsha.ComputeHash([Text.Encoding]::ASCII.GetBytes($urlQuery))
$token = [Convert]::ToBase64String($signature)


Generate a token in .NET C#

using System.Security.Cryptography;

var encoding = new System.Text.ASCIIEncoding();
byte[] messageBytes = encoding.GetBytes("QUERY_STRING");
byte[] keyByte = encoding.GetBytes("SECRET_API_KEY");
using (var hmacsha256 = new HMACSHA256(keyByte))
{
   byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
   var token = Convert.ToBase64String(hashmessage);
}

Generate a token in Shell (BASH etc)

QUERY_STRING="QUERY_STRING"
SECRET_API_KEY="SECRET_API_KEY"

echo -n $QUERY_STRING | openssl dgst -sha256 -hmac $SECRET_API_KEY -binary | base64

View more examples, where the "message" is the URL query string and the "secet" is your Secret API key: