For additional security, you can authenticate GET requests using a signed querystring. This method ensures that the request has not been tampered with and comes from a trusted source.

Signed requests are only supported for GET requests.

​
What is a Signed Request?

A signed request uses your secret key to generate a SHA-256 hash of the querystring. This hash is then included in the request as a signature parameter. When our servers receive the request, they verify the signature using the same secret key.

​
Your Secret Key

  • Your secret_key is unique to your account.
  • It is only visible in your dashboard.
  • Never share your secret key publicly.
  • You can rotate your secret key at any time via the dashboard.
If your secret key is exposed or compromised, rotate it immediately.

​
Enforce Signed GET Requests

From your dashboard, you can enforce signature validation for all GET requests by enabling the option: “Accept only signed requests”

Once enabled:

  • Any unsigned GET request will be rejected.
  • This setting does not affect POST or other non-GET requests.
  • You can toggle this option from the Access Control Management section in your dashboard.

​
How to Sign a Request

​
1. Start with your full querystring (everything after the ?)

Example of querystring:

url=https://example.com&access_key=YOUR_ACCESS_KEY

​
2. Do not include the signature parameter (yet)!

​
3. Compute the SHA-256 HMAC of the querystring using your secret_key

Node.js Example

const crypto = require("crypto");

const queryString = "url=https://example.com&access_key=YOUR_ACCESS_KEY";
const secretKey = "YOUR_SECRET_KEY";

const signature = crypto
  .createHmac("sha256", secretKey)
  .update(queryString)
  .digest("hex");

console.log(signature);

Python Example

import hmac
import hashlib

query_string = "url=https://example.com&access_key=YOUR_ACCESS_KEY"
secret_key = b"YOUR_SECRET_KEY"  # must be bytes

signature = hmac.new(secret_key, query_string.encode("utf-8"), hashlib.sha256).hexdigest()

print(signature)

​
4. Add the signature parameter to your final querystring

?url=https://example.com&access_key=YOUR_ACCESS_KEY&signature=computed_signature

​
Rotating the Secret Key

Just like the access_key, you can rotate your secret_key from your dashboard. After rotation:

  • A new secret key will be generated.
  • The old one will become invalid.
  • Make sure to update all your signing logic with the new key.

Example (Full URL)

GET https://api.screenshotmax.com/v1/screenshot
?url=https://example.com
&access_key=YOUR_ACCESS_KEY
&signature=2f3a5c9d...

​
Important Notes

  • The order of query parameters must be preserved exactly when generating the signature.
  • Do not include the signature parameter itself in the string you hash.
  • Only use this method for GET requests. It is not supported for POST or other methods.

​
Test Your Signature

We recommend verifying your implementation in a development environment before going live.

​
Why Use Signed Requests?

Signed requests add an extra layer of protection, ensuring:

  • The request hasn’t been modified in transit.
  • The request originates from a trusted client with access to the secret key.
  • You can optionally enforce this behavior for all GET calls to your API.

Need help? Contact us at support@screenshotmax.com