Sessions and cookies

Use the session object on a screenshot request when the target website needs your authorized session. This is separate from the X-API-Key header, which authenticates your request to Allscreenshots.

Keep credentials in server-side secrets. Supply only the target site's cookies or scoped headers needed for the capture, and use a dedicated account with limited access where possible.

Cookies

{
  "url": "https://app.example.com/report",
  "format": "png",
  "fullPage": true,
  "session": {
    "cookies": [
      {
        "name": "session",
        "value": "REPLACE_ON_YOUR_SERVER",
        "domain": "app.example.com",
        "path": "/",
        "secure": true,
        "httpOnly": true,
        "sameSite": "lax"
      }
    ]
  }
}

A request can provide up to 200 cookies. Cookie names are limited to 512 characters and values to 4,096. expires, when provided, is a Unix timestamp in seconds. An expired or incorrect session can still render a login page successfully: inspect the output before treating it as the report you intended to capture.

Origin-scoped headers

{
  "session": {
    "headers": [
      {
        "origin": "https://app.example.com",
        "name": "Authorization",
        "value": "Bearer TARGET_SITE_TOKEN"
      }
    ]
  }
}

Use an explicit origin for sensitive headers so they are scoped to the target origin. Up to 100 headers are accepted. Origins contain the scheme and host, without a path; values cannot contain line breaks. This target-site token is not an Allscreenshots API key.

Browser storage

If your application uses browser storage, provide entries for up to five origins:

{
  "session": {
    "storage": [
      {
        "origin": "https://app.example.com",
        "localStorage": { "theme": "dark" },
        "sessionStorage": { "reportView": "summary" }
      }
    ]
  }
}

Each origin accepts up to 200 entries in each storage map. Set only the values your app requires. A capture is not an interactive login flow; if the page needs a click or navigation after loading, combine the session with interactive actions and the waitFor selector.

Verify the result

Test a small capture with the target account, check that protected content appears, then test an expired session. Do not log request bodies containing session credentials or publish captures containing private data. Revalidate the setup when the target site's authentication changes.