Authentication

Every request to the ScreenshotBuddy API is authenticated with an API token that belongs to your account. This guide shows you where to create one, how to send it, and what happens when you do not.

Creating a token

A token is a long random string that stands in for your account. You can hold as many as you like, so give each application its own: revoking one then stops that application without touching the others.

Two things are decided when you create one: what it is allowed to do, and how long it lives. Both are covered below, and both can be changed later without touching the rest of your keys.

What a token is allowed to do

A token carries one permission per mode of the /snap endpoint. screenshot lets it render images, and pdf lets it print PDFs, which is what pdf=true asks for. A new token holds both, so nothing has to be configured before your first call.

Narrowing one is worth doing when a key only ever needs half of that. A service that renders thumbnails and nothing else can hold a screenshot only token, and a leak of that key cannot be turned into PDF rendering on your account.

A request for a mode the token was not granted is answered with HTTP status 403 and the missing_ability code. Nothing is rendered and no credit is spent. Tick the missing permission under Settings » API tokens and the same request works.

How long a token lives

By default a token has no expiry: it keeps working until you revoke or rotate it. When you create one you can give it a lifetime instead, and it stops working on its own once that runs out. That is worth choosing for a key handed to a contractor, a one-off migration or anything else you already know the end date of.

An expired token is refused the same way an unknown one is: HTTP status 401 with the unauthenticated code, shown below. The expiry of every token is listed under Settings » API tokens, so you can see what is about to run out before it does.

Rotating a token

Rotating replaces a token with a fresh one that keeps its name and its permissions, and shows you the new secret once. If the token had a lifetime, the replacement gets the same lifetime again, counted from the moment you rotate.

The token you replaced stops working immediately, so put the new secret in place first, or rotate at a moment the integration can be updated straight away. It is the quickest answer to a leak, and to the routine of changing a long lived key every so often.

Sending your token

Put the token in the Authorization header of every request, as a bearer token. There is no other way to authenticate: the API does not read tokens from the query string or from a cookie.

Header: Authorization: Bearer {token}
Note: Replace {token} with the token you created in your dashboard.

curl "https://screenshotbuddy.io/api/v1/snap?url=https%3A%2F%2Fexample.com" \
  -H "Authorization: Bearer {token}" \
  --output screenshot.png

Keeping your token safe

A token is as good as your password: anyone holding it can render pages and spend your credits. Keep it on your server, in an environment variable or a secrets manager, and let your own backend make the call.

Never put a token in client-side code. Anything that reaches a browser or a mobile app can be read out of it, including JavaScript bundles, source maps and network traces, so a token used from the browser is a published token.

If a token does leak, revoke it under Settings » API tokens and create a new one. Revoking is immediate, and the leaked token stops working on the next request.

When authentication fails

A request without a token, or with one that is unknown or revoked, is answered with HTTP status 401 and this body. You get JSON whatever Accept header you send, so a plain client never lands on an HTML login page.

{
    "code": "unauthenticated",
    "message": "Unauthenticated.",
    "request_id": "1f3c0e6a-6a5d-4a4c-9a3f-0a3f7d1c2b84"
}

Branch on code rather than on message: the code is a stable contract, while the message is written for a person and may be reworded. Keep the request_id as well, so you can quote it if you ask us about a failure.

A valid token is not enough on its own: the email address of the account has to be verified. Until it is, the API answers 403 with the email_unverified code. Verifying the address in your dashboard is all it takes.

Every other way a request can fail is listed on the errors page.