Docs

How to Screenshot Pages That Require Authentication

If you need to capture a screenshot of a URL that requires authentication, there are a few options available to you when using our screenshot API:

  1. Pass session cookies with your screenshot request
  2. Pass an Authorization header with your screenshot request

Cookies

If you need to capture a screenshot of a web page behind a login, pass your session cookie in the screenshot request.

Imagine you want to capture a screenshot of the dashboard page in your Screenshot Scout account. Here is what you need to do.

First, log in to your account in the browser using your email and password.

After you have logged in, if you are using Chrome, press F12 and go to the Application tab. In the left side panel, under Storage > Cookies, find https://screenshotscout.com. Then find only the cookies created by screenshotscout.com.

In the case of Screenshot Scout, the cookie name you are looking for is __Secure-better-auth.session_token. Depending on the site, this can be different.

Copy all the cookie parameters you see in your browser. In the case of Screenshot Scout, you will copy Name, Value, Domain, Path, HttpOnly, Secure, and SameSite.

Screenshot Scout - DevTools cookies

Format the cookie parameters you collected using this Set-Cookie-like format:

__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax

Pass the formatted string in the cookies option:

import { writeFile } from "node:fs/promises";
import { ScreenshotScoutClient } from "@screenshotscout/sdk";

const client = new ScreenshotScoutClient(); // Reads SCREENSHOTSCOUT_ACCESS_KEY

const response = await client.capture("https://screenshotscout.com/app/dashboard", {
  cookies: [
    "__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax",
  ],
});

await writeFile("screenshot.png", response.bytes);
from pathlib import Path

from screenshotscout import CaptureOptions, ScreenshotScoutClient

client = ScreenshotScoutClient()  # Reads SCREENSHOTSCOUT_ACCESS_KEY

response = client.capture(
    "https://screenshotscout.com/app/dashboard",
    CaptureOptions(
        cookies=[
            "__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax",
        ],
    ),
)

Path("screenshot.png").write_bytes(response.bytes)
import com.screenshotscout.BinaryCaptureResponse;
import com.screenshotscout.CaptureOptions;
import com.screenshotscout.ScreenshotScoutClient;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = ScreenshotScoutClient.fromEnv(); // Reads SCREENSHOTSCOUT_ACCESS_KEY

        var options = CaptureOptions.builder()
                .cookies(List.of(
                        "__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax"))
                .build();

        var response = (BinaryCaptureResponse) client.capture("https://screenshotscout.com/app/dashboard", options);
        Files.write(Path.of("screenshot.png"), response.bytes());
    }
}
using ScreenshotScout;

using var client = new ScreenshotScoutClient(); // Reads SCREENSHOTSCOUT_ACCESS_KEY

var response = (BinaryCaptureResponse)await client.CaptureAsync(
    "https://screenshotscout.com/app/dashboard",
    new CaptureOptions
    {
        Cookies =
        [
            "__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax",
        ],
    });

await File.WriteAllBytesAsync("screenshot.png", response.Bytes);
<?php

use ScreenshotScout\CaptureOptions;
use ScreenshotScout\Client;

require __DIR__ . '/vendor/autoload.php';

$client = new Client(); // Reads SCREENSHOTSCOUT_ACCESS_KEY

$response = $client->capture(
    'https://screenshotscout.com/app/dashboard',
    (new CaptureOptions())
        ->withCookies([
            '__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax',
        ]),
);

file_put_contents('screenshot.png', $response->bytes());
package main

import (
	"context"
	"log"
	"os"

	screenshotscout "github.com/screenshotscout/screenshotscout-go"
)

func main() {
	client, err := screenshotscout.NewClient() // Reads SCREENSHOTSCOUT_ACCESS_KEY
	if err != nil {
		log.Fatal(err)
	}

	response, err := client.Capture(context.Background(), "https://screenshotscout.com/app/dashboard", &screenshotscout.CaptureOptions{
		Cookies: []string{
			"__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax",
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	if err := os.WriteFile("screenshot.png", response.Binary.Bytes, 0o644); err != nil {
		log.Fatal(err)
	}
}
require "screenshotscout"

client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY

response = client.capture(
  "https://screenshotscout.com/app/dashboard",
  ScreenshotScout::CaptureOptions.new(
    cookies: [
      "__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax"
    ]
  )
)

File.binwrite("screenshot.png", response.bytes)
curl "https://api.screenshotscout.com/v1/capture" \
  -H "Authorization: Bearer $SCREENSHOTSCOUT_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://screenshotscout.com/app/dashboard",
    "cookies": [
      "__Secure-better-auth.session_token=CQhDDUmP4XFMCArVPuOWfc6du7rfzx83.5QEpu7%2FRgICZB%2Bl%2BADU0Zd64v5wC%2BDqypNIAqEUwWTI%3D; Domain=screenshotscout.com; Path=/; HttpOnly; Secure; SameSite=Lax"
    ]
  }' \
  -o "screenshot.png"

If you have collected all the necessary cookie parameters and formatted them properly, your screenshot will now show the correct destination page behind the login, not the login page itself.

Authorization header

If the URL you need to capture a screenshot of supports the Authorization header, you can pass it in the headers option:

import { writeFile } from "node:fs/promises";
import { ScreenshotScoutClient } from "@screenshotscout/sdk";

const client = new ScreenshotScoutClient(); // Reads SCREENSHOTSCOUT_ACCESS_KEY

const response = await client.capture("https://example.com/", {
  headers: ["Authorization: Bearer YOUR_BEARER_TOKEN"],
});

await writeFile("screenshot.png", response.bytes);
from pathlib import Path

from screenshotscout import CaptureOptions, ScreenshotScoutClient

client = ScreenshotScoutClient()  # Reads SCREENSHOTSCOUT_ACCESS_KEY

response = client.capture(
    "https://example.com/",
    CaptureOptions(
        headers=["Authorization: Bearer YOUR_BEARER_TOKEN"],
    ),
)

Path("screenshot.png").write_bytes(response.bytes)
import com.screenshotscout.BinaryCaptureResponse;
import com.screenshotscout.CaptureOptions;
import com.screenshotscout.ScreenshotScoutClient;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = ScreenshotScoutClient.fromEnv(); // Reads SCREENSHOTSCOUT_ACCESS_KEY

        var options = CaptureOptions.builder()
                .headers(List.of("Authorization: Bearer YOUR_BEARER_TOKEN"))
                .build();

        var response = (BinaryCaptureResponse) client.capture("https://example.com/", options);
        Files.write(Path.of("screenshot.png"), response.bytes());
    }
}
using ScreenshotScout;

using var client = new ScreenshotScoutClient(); // Reads SCREENSHOTSCOUT_ACCESS_KEY

var response = (BinaryCaptureResponse)await client.CaptureAsync(
    "https://example.com/",
    new CaptureOptions
    {
        Headers = ["Authorization: Bearer YOUR_BEARER_TOKEN"],
    });

await File.WriteAllBytesAsync("screenshot.png", response.Bytes);
<?php

use ScreenshotScout\CaptureOptions;
use ScreenshotScout\Client;

require __DIR__ . '/vendor/autoload.php';

$client = new Client(); // Reads SCREENSHOTSCOUT_ACCESS_KEY

$response = $client->capture(
    'https://example.com/',
    (new CaptureOptions())
        ->withHeaders(['Authorization: Bearer YOUR_BEARER_TOKEN']),
);

file_put_contents('screenshot.png', $response->bytes());
package main

import (
	"context"
	"log"
	"os"

	screenshotscout "github.com/screenshotscout/screenshotscout-go"
)

func main() {
	client, err := screenshotscout.NewClient() // Reads SCREENSHOTSCOUT_ACCESS_KEY
	if err != nil {
		log.Fatal(err)
	}

	response, err := client.Capture(context.Background(), "https://example.com/", &screenshotscout.CaptureOptions{
		Headers: []string{"Authorization: Bearer YOUR_BEARER_TOKEN"},
	})
	if err != nil {
		log.Fatal(err)
	}

	if err := os.WriteFile("screenshot.png", response.Binary.Bytes, 0o644); err != nil {
		log.Fatal(err)
	}
}
require "screenshotscout"

client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY

response = client.capture(
  "https://example.com/",
  ScreenshotScout::CaptureOptions.new(
    headers: ["Authorization: Bearer YOUR_BEARER_TOKEN"]
  )
)

File.binwrite("screenshot.png", response.bytes)
curl "https://api.screenshotscout.com/v1/capture" \
  -H "Authorization: Bearer $SCREENSHOTSCOUT_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/",
    "headers": ["Authorization: Bearer YOUR_BEARER_TOKEN"]
  }' \
  -o "screenshot.png"