Send a screenshot API to your admin panel URL and what comes back is the login form. The headless browser on the API side has never visited your site before -- no session, no stored credentials. The server sees an anonymous request and responds exactly as it would to any stranger: it redirects to login.
I ran into this with fixheaders.com, my own security headers scanner. The Filament admin panel shows scan counts and score distributions, and I wanted a periodic screenshot of that dashboard without logging in manually each time. Getting a session cookie across to the headless renderer turned out to have a few more wrinkles than I expected.
For a broader overview of authenticated screenshot workflows, see the Screenshot API for Pages Behind Login use-case page. This post is about the implementation: session cookies, custom HTTP headers, Basic Auth, and automating login when sessions expire. Code examples run across cURL, Node.js, Python, and PHP throughout.
Why a regular screenshot request won't work
When you ask a screenshot API -- or run Playwright or Puppeteer yourself -- to capture a URL, the headless browser opens it as a first-time visitor. It carries no session and no stored credentials from any previous visit. The server treats it exactly as it would an unauthenticated user: redirect to login, or show the login form directly.
This is what happens when you send a request to the fixheaders.com admin URL with no cookies at all:
curl -X POST https://api.screenshotrun.com/v1/screenshots \
-H "Authorization: Bearer $SCREENSHOTRUN_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://fixheaders.com/admin"}'

After a few seconds we can download the result:
curl -H "Authorization: Bearer $SCREENSHOTRUN_KEY" \
https://api.screenshotrun.com/v1/screenshots/SCREENSHOT_ID/image \
-o screenshot-no-auth.png

Open the file and -- yeah, exactly what you'd expect:
Same thing as opening the URL in an incognito window. The fix is to give the headless browser the same credentials your regular browser already holds.
Method 1: pass session cookies
Most web apps use cookie-based sessions -- Laravel, Django, Rails, WordPress, any Filament admin panel. When you log in, the server creates a session record and sends a cookie. Every subsequent request includes that cookie so the server recognizes you.
Give that same cookie to the screenshot API. The headless browser sends it with the request, the server sees a valid session, and you get a screenshot of the actual dashboard instead of the login page.
Step 1: find your session cookie
Open the site you want to screenshot and log in normally. Then open DevTools → Application → Cookies (Chrome) or Storage → Cookies (Firefox).
Look for the session cookie. In Laravel apps it's usually called laravel_session or a custom name from config/session.php -- in my case it's fixheaders-session. Other frameworks name it differently: PHPSESSID in plain PHP, sessionid in Django, _yourapp_session in Rails.
Copy the cookie value. It'll look something like this:
eyJpdiI6IkxMNk1DVjZhN0FKWjZ2a3...long_base64_string
Step 2: pass it to the screenshot API
Send that cookie with a ScreenshotRun API request like this.
cURL:
curl -X POST https://api.screenshotrun.com/v1/screenshots \
-H "Authorization: Bearer $SCREENSHOTRUN_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://fixheaders.com/admin",
"cookies": [
{
"name": "fixheaders-session",
"value": "eyJpdiI6IkxMNk1DVjZhN0FKWjZ2a3...",
"domain": "fixheaders.com"
}
]
}'

The cookies parameter takes an array of objects. Each one needs a name, value, and domain. The domain tells the browser which site to attach the cookie to -- without it the cookie may not reach the request at all.
Download the result using the ID from the response:
curl -H "Authorization: Bearer $SCREENSHOTRUN_KEY" \
https://api.screenshotrun.com/v1/screenshots/SCREENSHOT_ID/image \
-o screenshot-with-auth.png
And here's what we get this time:
The actual dashboard: scan counts, average score, recent checks. One cookie made all the difference.
Node.js:
const response = await fetch("https://api.screenshotrun.com/v1/screenshots", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://fixheaders.com/admin",
cookies: [
{
name: "fixheaders-session",
value: "eyJpdiI6IkxMNk1DVjZhN0FKWjZ2a3...",
domain: "fixheaders.com",
},
],
}),
});
const { data } = await response.json();
console.log(data.id);
Python:
import requests
response = requests.post(
"https://api.screenshotrun.com/v1/screenshots",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"url": "https://fixheaders.com/admin",
"cookies": [
{
"name": "fixheaders-session",
"value": "eyJpdiI6IkxMNk1DVjZhN0FKWjZ2a3...",
"domain": "fixheaders.com",
}
],
},
)
screenshot_id = response.json()["data"]["id"]
print(f"Screenshot ID: {screenshot_id}")
PHP (Laravel):
If you haven't set up the screenshot API in PHP yet, see the PHP screenshot tutorial. The short version for authenticated pages:
$response = Http::withToken(env('SCREENSHOTRUN_API_KEY'))
->post('https://api.screenshotrun.com/v1/screenshots', [
'url' => 'https://fixheaders.com/admin',
'cookies' => [
[
'name' => 'fixheaders-session',
'value' => 'eyJpdiI6IkxMNk1DVjZhN0FKWjZ2a3...',
'domain' => 'fixheaders.com',
],
],
]);
$screenshotId = $response->json('data.id');
After the request completes, poll the screenshot status or use a webhook to get notified when it's ready.
What can go wrong with cookies
Session expiration is the most common issue. Session cookies have a lifetime -- Laravel's default is 2 hours. After that the session is invalid and the screenshot comes back as the login page again. If you're automating this, you need to refresh the cookie periodically. The cleaner solution is a script that logs in programmatically each time, which is covered in the automation section below.
Some apps set multiple cookies on login -- the session itself plus a "remember me" token or a CSRF cookie that the app validates on every request. If your screenshot keeps coming back as a login page despite passing the right session cookie, open DevTools while logged in and check how many cookies are actually there. You can pass up to 20 cookies in a single request, so covering all of them is straightforward once you know what they are.
Session cookies marked as HttpOnly (not readable by JavaScript) and Secure (HTTPS only) work normally with the screenshot API. The headless browser handles these flags the same way a regular browser does. Just make sure you're passing HTTPS URLs.
What about SameSite=Strict? Because the screenshot API's headless browser navigates directly to the URL as a top-level navigation -- not a cross-origin fetch -- SameSite=Strict cookies are included normally. No special handling needed.
Method 2: custom HTTP headers (API tokens and Bearer auth)
Not every protected page uses session cookies. Some internal tools check for a custom HTTP header instead -- an X-Auth-Token or a Bearer token that the server validates before serving any content. API documentation portals and headless CMS backends often use this pattern.
If the page checks for a specific header rather than a cookie, the headers parameter handles it.
cURL:
curl -X POST https://api.screenshotrun.com/v1/screenshots \
-H "Authorization: Bearer $SCREENSHOTRUN_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://internal-tool.example.com/dashboard",
"headers": {
"X-Auth-Token": "your-internal-token-here"
}
}'
Node.js:
const response = await fetch("https://api.screenshotrun.com/v1/screenshots", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://internal-tool.example.com/dashboard",
headers: {
"X-Auth-Token": "your-internal-token-here",
},
}),
});
Python:
import requests
response = requests.post(
"https://api.screenshotrun.com/v1/screenshots",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"url": "https://internal-tool.example.com/dashboard",
"headers": {
"X-Auth-Token": "your-internal-token-here",
},
},
)
screenshot_id = response.json()["data"]["id"]
PHP:
$response = Http::withToken(env('SCREENSHOTRUN_API_KEY'))
->post('https://api.screenshotrun.com/v1/screenshots', [
'url' => 'https://internal-tool.example.com/dashboard',
'headers' => [
'X-Auth-Token' => 'your-internal-token-here',
],
]);
The headers parameter accepts an object where keys are header names and values are header values. Up to 20 custom headers per request.
One thing worth spelling out: the Authorization header inside the headers parameter goes to the target page, not to the ScreenshotRun API. Your API key for ScreenshotRun always goes in the top-level Authorization header of the HTTP request itself. The headers object is what the headless browser sends when loading the target URL. Easy to mix up the first time you write this.
Method 3: Basic Auth for staging and htpasswd-protected sites
If you've ever password-protected a staging server with Nginx's auth_basic or Apache's .htpasswd, you know the pattern: the browser shows a dialog asking for a username and password before the page even loads. Headless browsers can't interact with that dialog, so the request fails or returns a 401.
The fix is straightforward -- send the credentials as a Basic Auth header. The server gets them before it has a chance to ask, the page loads, and the headless browser never sees the dialog at all.
cURL:
curl -X POST https://api.screenshotrun.com/v1/screenshots \
-H "Authorization: Bearer $SCREENSHOTRUN_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://staging.example.com",
"headers": {
"Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
}
}'
Basic dXNlcm5hbWU6cGFzc3dvcmQ= is username:password encoded in Base64. Generate it from the terminal:
echo -n "username:password" | base64
# Output: dXNlcm5hbWU6cGFzc3dvcmQ=
Node.js:
const credentials = Buffer.from("username:password").toString("base64");
const response = await fetch("https://api.screenshotrun.com/v1/screenshots", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://staging.example.com",
headers: {
"Authorization": `Basic ${credentials}`,
},
}),
});
Python:
import base64
import requests
credentials = base64.b64encode(b"username:password").decode()
response = requests.post(
"https://api.screenshotrun.com/v1/screenshots",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"url": "https://staging.example.com",
"headers": {
"Authorization": f"Basic {credentials}",
},
},
)
screenshot_id = response.json()["data"]["id"]
PHP:
$credentials = base64_encode('username:password');
$response = Http::withToken(env('SCREENSHOTRUN_API_KEY'))
->post('https://api.screenshotrun.com/v1/screenshots', [
'url' => 'https://staging.example.com',
'headers' => [
'Authorization' => 'Basic ' . $credentials,
],
]);
Works for any site using HTTP Basic Authentication -- common on staging environments and dev servers.
Combining cookies with other capture options
All three authentication methods work alongside the regular screenshot parameters. For the full list, see the cookie blocking and custom viewport feature pages. You can capture a full-page screenshot of an authenticated dashboard in dark mode, at a mobile viewport, with cookie banners blocked -- all in one request:
curl -X POST https://api.screenshotrun.com/v1/screenshots \
-H "Authorization: Bearer $SCREENSHOTRUN_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://fixheaders.com/admin",
"cookies": [
{
"name": "fixheaders-session",
"value": "your-session-cookie-value",
"domain": "fixheaders.com"
}
],
"full_page": true,
"dark_mode": true,
"device": "mobile",
"format": "webp"
}'
The full parameters list (dark mode, device presets, CSS injection and element selectors) is in the API documentation. The cURL examples article walks through each capture option with copy-paste commands.
Automating the login (when cookies expire too fast)
If you need authenticated screenshots on a schedule -- say, every hour for a dashboard you embed somewhere -- manually copying cookies won't work. Sessions expire, and when they do, your screenshot reverts to the login page.
Instead of grabbing cookies by hand, write a script that logs in programmatically and extracts a fresh session cookie each run. That cookie goes straight into the screenshot request.
A Node.js example using plain fetch (if you need more context on Node.js setup, see the full Node.js tutorial):
async function getSessionCookie(loginUrl, email, password) {
const response = await fetch(loginUrl, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email, password }),
redirect: "manual",
});
const setCookie = response.headers.get("set-cookie");
if (!setCookie) {
throw new Error("No Set-Cookie header in login response");
}
const match = setCookie.match(/(\w+[-_]session)=([^;]+)/);
if (!match) {
throw new Error("Could not find session cookie in Set-Cookie header");
}
return { name: match[1], value: match[2] };
}
// Usage
const cookie = await getSessionCookie(
"https://fixheaders.com/login",
"[email protected]",
"your-password"
);
const response = await fetch("https://api.screenshotrun.com/v1/screenshots", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://fixheaders.com/admin",
cookies: [
{
name: cookie.name,
value: cookie.value,
domain: "fixheaders.com",
},
],
}),
});
The login endpoint varies by framework. Laravel's default is POST /login with email and password fields. Django uses POST /accounts/login/. WordPress takes POST /wp-login.php with log and pwd. Worth reading the form action in DevTools if it's not obvious.
The CSRF token problem
Most frameworks protect login forms with CSRF tokens. POST to /login without a valid token and you'll get a 419 from Laravel or a 403 from Django and Rails. You need to GET the login page first, extract the CSRF token, then include it in the POST.
In Laravel the token lives in a cookie called XSRF-TOKEN (URL-encoded) and needs to come back as an X-XSRF-TOKEN header or _token form field:
async function laravelLogin(baseUrl, email, password) {
// Step 1: GET the login page to grab the CSRF cookie
const loginPage = await fetch(`${baseUrl}/login`);
const csrfCookie = loginPage.headers
.get("set-cookie")
?.match(/XSRF-TOKEN=([^;]+)/)?.[1];
if (!csrfCookie) {
throw new Error("Could not extract CSRF token");
}
const csrfToken = decodeURIComponent(csrfCookie);
// Step 2: POST login credentials with the CSRF token
const response = await fetch(`${baseUrl}/login`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-XSRF-TOKEN": csrfToken,
Cookie: `XSRF-TOKEN=${csrfCookie}`,
},
body: JSON.stringify({ email, password }),
redirect: "manual",
});
// Step 3: extract the session cookie from the response
const sessionCookie = response.headers
.get("set-cookie")
?.match(/(\w+[-_]session)=([^;]+)/);
if (!sessionCookie) {
throw new Error("Login failed — no session cookie returned");
}
return { name: sessionCookie[1], value: sessionCookie[2] };
}
More work than copying from DevTools, but it runs unattended and the session is always fresh. I use a variation of this inside screenshotrun's renderer when testing authenticated pages in development.
Choosing the right method
Session cookies cover the majority of real-world cases -- any app built on a web framework with server-side sessions. If you're not sure which method applies, start there.
Custom headers fit tools that issue static API tokens or Bearer tokens -- usually internal tools, headless CMSes, or admin interfaces that authenticate via token rather than interactive login. Worth checking the app's network requests in DevTools: if you see an X-Auth-Token or Authorization: Bearer ... header on page loads, that's your signal.
Basic Auth is the fastest to set up and covers the entire Nginx/Apache htpasswd pattern. If you're screenshotting staging servers, this is almost certainly what you need.
Some setups stack multiple layers -- a staging server might have Basic Auth at the Nginx level AND cookie-based sessions at the application level. In that case, pass both: the headers parameter with the Basic Auth header and the cookies parameter with the session cookie. The API sends everything together.
For a broader overview of which method fits which workflow, see the authenticated screenshots use-case page.
Troubleshooting: screenshot still showing the login page
You've passed the cookie, the request returns 200 -- but the screenshot is still the login form. A few things worth checking:
- Cookie expired. Session cookies have a lifetime (2 hours in Laravel by default). If you grabbed the cookie hours ago, it's likely invalid. Re-login in your browser and copy a fresh value.
- Wrong domain. The
domainfield must match exactly.fixheaders.comandwww.fixheaders.comare different cookie scopes. Check which domain the cookie is set to in DevTools. - Missing additional cookies. Some apps set multiple cookies on login -- session, CSRF, "remember me". Open DevTools → Application → Cookies while logged in, and pass everything that looks non-trivial.
- CSRF token required on every page load. Some frameworks validate a CSRF token even for GET requests on protected pages. Use the programmatic login approach above to handle this automatically.
- IP-based session validation. Some apps or Nginx configurations tie sessions to a specific IP. The screenshot API's server IP won't match your browser's IP -- the session gets invalidated on first use from an unfamiliar address. If this is the case, automate the full login flow so the headless browser builds its own session from scratch.
Security notes
Don't hardcode credentials in source code. Store session cookies and API tokens in environment variables, never in committed files. One accidental git push can expose them.
If you're automating dashboard screenshots, create a dedicated read-only account for this purpose. Don't use admin credentials in scripts. If the script gets compromised, a read-only account limits the blast radius significantly.
Authenticated screenshots often capture sensitive content -- revenue numbers, user data, internal metrics. If you're storing these images long-term or serving them from a cache, think carefully about who has access. A publicly guessable URL containing a screenshot of your admin panel is a problem regardless of how the original request was authenticated.
Session cookies are credentials. Keep them in environment variables, out of logs, and never in plain HTTP requests. Always use HTTPS URLs with the screenshot API.
What I ended up doing with fixheaders
Back to the original problem. I needed periodic screenshots of fixheaders.com scan stats without logging in manually.
What I landed on: a Laravel scheduled task (schedule:run) that fires every hour. It runs the programmatic login against fixheaders, extracts a fresh session cookie, takes a screenshot of the admin dashboard, and saves it. I can open the latest file any time and see current numbers without touching a browser.
Could I have built a proper API for the stats instead? Yes. Would have taken considerably longer than the 20 minutes this approach took. Sometimes a screenshot is the fastest way to pull data out of a system that doesn't expose it any other way.
One thing worth knowing before you start: the cookies and headers parameters are available on the Pro plan and above, not on the free tier.
If you hit edge cases with specific auth setups -- NextAuth, Passport, Sanctum all have quirks -- feel free to reach out and I'll try to help.
FAQ#
Grab the session cookie from your browser (DevTools → Application → Cookies), then pass it to the screenshot tool or API. The headless browser sends that cookie with the request, the server sees a valid session, and you get the authenticated page instead of the login form.
The screenshot reverts to showing the login page. Session cookies have a limited lifetime (2 hours by default in Laravel, for example). For automated captures, write a script that logs in programmatically via HTTP, extracts the fresh session cookie from the Set-Cookie header, and passes it to the screenshot request.
Send the credentials as a Base64-encoded Authorization header: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=. Generate the encoded string with echo -n "username:password" | base64. The headless browser sends this header and bypasses the native password dialog entirely.
Yes. Some setups need both — for example, a staging server with Basic Auth at the Nginx level and cookie-based sessions at the application level. Pass the Authorization header through the headers parameter and the session cookie through the cookies parameter. They get sent together.
Not recommended. Create a dedicated read-only account specifically for screenshot automation. Store its credentials in environment variables or a secrets manager, never in your codebase. Session cookies are temporary credentials too — treat them like passwords and don't log or expose them.