Signed Requests
Stop others from misusing the access key in capture URLs you share.
A capture URL contains your access key. Anyone who sees the URL, in a page's source code, an email or a chat, can copy the key and capture any page with it, using up your quota.
A signature prevents this. It's computed from the URL's options and your secret key, so it only fits that exact URL. Once you require signed requests for an API key, the API rejects every request that isn't signed with that key's secret key.
You only need signatures when capture URLs leave your server, for example in an <img> tag or an email. If only your server sends requests, you don't need them.
Get your secret key
Open the API Keys page. Each API key has an access key and a secret key. Copy the secret key of the API key you want to protect.
Keep the secret key on your server. Never put it in a web page, a mobile app or a URL: anyone who has it can sign any request. The SDKs use it to compute signatures locally and never send it anywhere.
Sign your capture URLs
Set the secret key as the SCREENSHOTSCOUT_SECRET_KEY environment variable, next to SCREENSHOTSCOUT_ACCESS_KEY. Every capture URL the client builds then carries a signature:
import { ScreenshotScoutClient } from "@screenshotscout/sdk";
const client = new ScreenshotScoutClient(); // Reads SCREENSHOTSCOUT_ACCESS_KEY and SCREENSHOTSCOUT_SECRET_KEY
const captureUrl = client.buildCaptureUrl("https://example.com/");
console.log(captureUrl);from screenshotscout import ScreenshotScoutClient
client = ScreenshotScoutClient() # Reads SCREENSHOTSCOUT_ACCESS_KEY and SCREENSHOTSCOUT_SECRET_KEY
capture_url = client.build_capture_url("https://example.com/")
print(capture_url)import com.screenshotscout.ScreenshotScoutClient;
public class Main {
public static void main(String[] args) {
// Reads SCREENSHOTSCOUT_ACCESS_KEY and SCREENSHOTSCOUT_SECRET_KEY
var client = ScreenshotScoutClient.fromEnv();
var captureUrl = client.buildCaptureUrl("https://example.com/");
System.out.println(captureUrl);
}
}using ScreenshotScout;
using var client = new ScreenshotScoutClient(); // Reads SCREENSHOTSCOUT_ACCESS_KEY and SCREENSHOTSCOUT_SECRET_KEY
var captureUrl = client.BuildCaptureUrl("https://example.com/");
Console.WriteLine(captureUrl);<?php
use ScreenshotScout\Client;
require __DIR__ . '/vendor/autoload.php';
$client = new Client(); // Reads SCREENSHOTSCOUT_ACCESS_KEY and SCREENSHOTSCOUT_SECRET_KEY
$captureUrl = $client->buildCaptureUrl('https://example.com/');
echo $captureUrl . PHP_EOL;package main
import (
"fmt"
"log"
screenshotscout "github.com/screenshotscout/screenshotscout-go"
)
func main() {
// Reads SCREENSHOTSCOUT_ACCESS_KEY and SCREENSHOTSCOUT_SECRET_KEY
client, err := screenshotscout.NewClient()
if err != nil {
log.Fatal(err)
}
captureURL, err := client.BuildCaptureURL("https://example.com/", nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(captureURL)
}require "screenshotscout"
client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY and SCREENSHOTSCOUT_SECRET_KEY
capture_url = client.build_capture_url("https://example.com/")
puts capture_urlEach example prints a signed capture URL like this one:
https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https%3A%2F%2Fexample.com%2F&signature=b56c41ea153c60ba222c177cd2a95ce343781d1d28ed8bbdc203a847a99752f4Open it in a browser to check that it works, then use it wherever a browser loads it, such as the src of an <img> tag. The URL doesn't expire, so if it may be loaded many times, you can set cache: repeat loads are then served from the cache and don't count toward your monthly quota.
The same client also signs its capture requests.
Require signed requests
Once you require signed requests for an API key, the API rejects every request made with that key that doesn't have a valid signature. Before you turn it on, make sure everything that uses the key sends signed GET requests:
- SDK clients: set the secret key, as in the previous step.
- The CLI: set
SCREENSHOTSCOUT_SECRET_KEY. See Set your credentials. - The local MCP server and the Claude Desktop extension: add the secret key. See MCP.
- The hosted MCP endpoint: it can't sign requests. Use the local MCP server instead, or a different API key.
- Your own HTTP code: compute signatures as described in Sign requests without an SDK.
To require signed requests for an existing key, open the API Keys page, click the three-dots icon (⋯) next to the key, then click Edit API key. Turn on Require signed requests, then click Save.
The change takes effect immediately. From then on, requests without a signature fail with signature_required, and requests with a wrong signature fail with signature_invalid.
Alternatively, keep your current key as it is and create a second API key with Require signed requests turned on. Use the new key only to build capture URLs, and your current key for everything else.
Troubleshooting
| What you see | What to do |
|---|---|
signature_required | The request has no signature. Either the client or tool that sent it doesn't have the secret key, or the request used POST, which can't be signed. Set SCREENSHOTSCOUT_SECRET_KEY for the SDK client, the CLI or the local MCP server. If you send requests yourself, sign them and use GET. |
signature_invalid | The signature doesn't match the request. Check that the secret key belongs to the same API key as the access key. Also check that nothing changed the URL after it was signed: an added, removed or changed parameter breaks the signature, and so does encoding the URL twice. If you compute signatures yourself, compare your output with the code examples. |
Errors lists every error code.
If your secret key is ever exposed, revoke the API key on the API Keys page and create a new one. You can't change the secret key on its own. Every URL made with the old key stops working right away.
Sign requests without an SDK
Use this section if there's no SDK for your language, if your runtime is older than the SDKs support (Node.js 22, Python 3.11, Java 17, .NET 8, PHP 8.3, Go 1.25 and Ruby 3.4), or if another tool builds your capture URLs.
How to compute a signature
- Collect every parameter of the request except
signature. Includeaccess_key, even when you send the key in theAuthorizationheader instead. - Sort the parameters by name. Parameters with the same name, such as two
hide_selectors, keep their original order. - Encode each name and value as UTF-8, then percent-encode every byte except
A–Z,a–z,0–9,-,.,_and~. Encode spaces as%20, and write hex digits in uppercase. - Join the pairs as
name=value, separated by&. The result is the canonical query string. - Compute the HMAC-SHA256 of the canonical query string, with your secret key as the key, and write the result as lowercase hex. Use the secret key as text: don't hex-decode it.
- Add the result to the URL as the
signatureparameter.
You can build the URL you send with any URL library. Only the canonical query string has to follow these rules exactly.
Only GET requests can be signed.
Code examples
These examples sign a capture URL for https://example.com/ with full_page and two hide_selectors, and print it. They use only the standard library, and run on Node.js 18, Python 3.9, Java 8, .NET 6, PHP 7.4, Go 1.18 and Ruby 2.7 or later.
const { createHmac } = require("node:crypto");
const accessKey = "YOUR_ACCESS_KEY";
const secretKey = "YOUR_SECRET_KEY"; // keep this on your server
// The options to sign. Repeat a name to send several values.
const params = [
["access_key", accessKey],
["url", "https://example.com/"],
["full_page", "true"],
["hide_selectors", '[class*="cookie"]'],
["hide_selectors", "#header ~ .promo"],
];
// Sort by name. sort() is stable, so repeated names keep their order.
const sorted = [...params].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
// Like encodeURIComponent, but ! ' ( ) and * are encoded too.
const encode = (text) =>
encodeURIComponent(text).replace(
/[!'()*]/g,
(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
);
const canonicalQuery = sorted
.map(([name, value]) => `${encode(name)}=${encode(value)}`)
.join("&");
const signature = createHmac("sha256", secretKey)
.update(canonicalQuery)
.digest("hex");
console.log(
`https://api.screenshotscout.com/v1/capture?${canonicalQuery}&signature=${signature}`,
);import hashlib
import hmac
from urllib.parse import quote
access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY" # keep this on your server
# The options to sign. Repeat a name to send several values.
params = [
("access_key", access_key),
("url", "https://example.com/"),
("full_page", "true"),
("hide_selectors", '[class*="cookie"]'),
("hide_selectors", "#header ~ .promo"),
]
def encode(text):
# safe="" encodes / too, which quote() leaves as it is by default.
return quote(text, safe="")
# Sort by name. sorted() is stable, so repeated names keep their order.
canonical_query = "&".join(
encode(name) + "=" + encode(value)
for name, value in sorted(params, key=lambda pair: pair[0])
)
signature = hmac.new(
secret_key.encode("utf-8"),
canonical_query.encode("utf-8"),
hashlib.sha256,
).hexdigest()
print(f"https://api.screenshotscout.com/v1/capture?{canonical_query}&signature={signature}")import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Comparator;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class Main {
public static void main(String[] args) throws Exception {
String accessKey = "YOUR_ACCESS_KEY";
String secretKey = "YOUR_SECRET_KEY"; // keep this on your server
// The options to sign. Repeat a name to send several values.
String[][] params = {
{"access_key", accessKey},
{"url", "https://example.com/"},
{"full_page", "true"},
{"hide_selectors", "[class*=\"cookie\"]"},
{"hide_selectors", "#header ~ .promo"},
};
// Sort by name. Arrays.sort is stable, so repeated names keep their order.
Arrays.sort(params, Comparator.comparing((String[] param) -> param[0]));
StringBuilder canonicalQuery = new StringBuilder();
for (String[] param : params) {
if (canonicalQuery.length() > 0) {
canonicalQuery.append('&');
}
canonicalQuery.append(encode(param[0])).append('=').append(encode(param[1]));
}
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
StringBuilder signature = new StringBuilder();
for (byte b : mac.doFinal(canonicalQuery.toString().getBytes(StandardCharsets.UTF_8))) {
signature.append(String.format("%02x", b));
}
System.out.println("https://api.screenshotscout.com/v1/capture?" + canonicalQuery + "&signature=" + signature);
}
// Like URLEncoder, but spaces become %20, * becomes %2A and ~ stays as it is.
static String encode(String text) throws Exception {
return URLEncoder.encode(text, "UTF-8").replace("+", "%20").replace("*", "%2A").replace("%7E", "~");
}
}using System.Security.Cryptography;
using System.Text;
var accessKey = "YOUR_ACCESS_KEY";
var secretKey = "YOUR_SECRET_KEY"; // keep this on your server
// The options to sign. Repeat a name to send several values.
var parameters = new (string Name, string Value)[]
{
("access_key", accessKey),
("url", "https://example.com/"),
("full_page", "true"),
("hide_selectors", "[class*=\"cookie\"]"),
("hide_selectors", "#header ~ .promo"),
};
// Sort by name. OrderBy is stable, so repeated names keep their order.
// Uri.EscapeDataString encodes names and values exactly the way the signature needs.
var canonicalQuery = string.Join("&", parameters
.OrderBy(parameter => parameter.Name, StringComparer.Ordinal)
.Select(parameter => Uri.EscapeDataString(parameter.Name) + "=" + Uri.EscapeDataString(parameter.Value)));
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));
var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(canonicalQuery));
var signature = Convert.ToHexString(hash).ToLowerInvariant();
Console.WriteLine($"https://api.screenshotscout.com/v1/capture?{canonicalQuery}&signature={signature}");<?php
$accessKey = 'YOUR_ACCESS_KEY';
$secretKey = 'YOUR_SECRET_KEY'; // keep this on your server
// The options to sign. Repeat a name to send several values.
$params = [
['access_key', $accessKey],
['url', 'https://example.com/'],
['full_page', 'true'],
['hide_selectors', '[class*="cookie"]'],
['hide_selectors', '#header ~ .promo'],
];
// Sort by name. usort() isn't stable before PHP 8.0,
// so ties are broken by position to keep repeated names in order.
$sorted = [];
foreach ($params as $position => [$name, $value]) {
$sorted[] = [$name, $value, $position];
}
usort($sorted, static function (array $left, array $right): int {
$byName = strcmp($left[0], $right[0]);
return $byName !== 0 ? $byName : $left[2] <=> $right[2];
});
// rawurlencode() encodes names and values exactly the way the signature needs.
$pairs = [];
foreach ($sorted as [$name, $value]) {
$pairs[] = rawurlencode($name) . '=' . rawurlencode($value);
}
$canonicalQuery = implode('&', $pairs);
$signature = hash_hmac('sha256', $canonicalQuery, $secretKey);
echo "https://api.screenshotscout.com/v1/capture?{$canonicalQuery}&signature={$signature}" . PHP_EOL;package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
"net/url"
"sort"
"strings"
)
func main() {
accessKey := "YOUR_ACCESS_KEY"
secretKey := "YOUR_SECRET_KEY" // keep this on your server
// The options to sign. Repeat a name to send several values.
params := [][2]string{
{"access_key", accessKey},
{"url", "https://example.com/"},
{"full_page", "true"},
{"hide_selectors", `[class*="cookie"]`},
{"hide_selectors", "#header ~ .promo"},
}
// Sort by name. SliceStable keeps repeated names in their order.
sort.SliceStable(params, func(i, j int) bool { return params[i][0] < params[j][0] })
// Like url.QueryEscape, but spaces become %20.
encode := func(text string) string { return strings.ReplaceAll(url.QueryEscape(text), "+", "%20") }
pairs := make([]string, len(params))
for i, param := range params {
pairs[i] = encode(param[0]) + "=" + encode(param[1])
}
canonicalQuery := strings.Join(pairs, "&")
mac := hmac.New(sha256.New, []byte(secretKey))
mac.Write([]byte(canonicalQuery))
signature := hex.EncodeToString(mac.Sum(nil))
fmt.Printf("https://api.screenshotscout.com/v1/capture?%s&signature=%s\n", canonicalQuery, signature)
}require "erb"
require "openssl"
access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY" # keep this on your server
# The options to sign. Repeat a name to send several values.
params = [
["access_key", access_key],
["url", "https://example.com/"],
["full_page", "true"],
["hide_selectors", '[class*="cookie"]'],
["hide_selectors", "#header ~ .promo"]
]
# Sort by name. sort_by isn't stable, so the index keeps repeated names in their order.
sorted = params.each_with_index.sort_by { |(name, _value), index| [name, index] }.map(&:first)
# ERB::Util.url_encode encodes names and values exactly the way the signature needs.
canonical_query = sorted.map { |name, value| "#{ERB::Util.url_encode(name)}=#{ERB::Util.url_encode(value)}" }.join("&")
signature = OpenSSL::HMAC.hexdigest("SHA256", secret_key, canonical_query)
puts "https://api.screenshotscout.com/v1/capture?#{canonical_query}&signature=#{signature}"With the placeholder keys, each one prints this URL:
https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&full_page=true&hide_selectors=%5Bclass%2A%3D%22cookie%22%5D&hide_selectors=%23header%20~%20.promo&url=https%3A%2F%2Fexample.com%2F&signature=80f916fc5ec735c6c5c5c4898d5245e4e9f0ebe6d2c597a51113e1b945eefe36If your code prints the same URL with the same keys, it signs correctly. If it doesn't, check the usual mistakes: spaces must become %20, * must become %2A, ~ must stay as it is, and the two hide_selectors must stay in their original order.
Check with OpenSSL
To check the signature of a canonical query string your code built, compute it with OpenSSL. This example uses the string the code examples sign:
# The canonical query string from the code examples
CANONICAL_QUERY='access_key=YOUR_ACCESS_KEY&full_page=true&hide_selectors=%5Bclass%2A%3D%22cookie%22%5D&hide_selectors=%23header%20~%20.promo&url=https%3A%2F%2Fexample.com%2F'
# HMAC-SHA256 of the string, keyed with your secret key
printf '%s' "$CANONICAL_QUERY" | openssl sha256 -hmac "YOUR_SECRET_KEY"It prints the same signature as the code examples, after SHA2-256(stdin)= , or after (stdin)= in OpenSSL 1.1. On Windows, run it in Git Bash or WSL.