How to Take Screenshots of Password-Protected Pages with ScreenshotOne

To screenshot a password-protected page with ScreenshotOne, use the authentication method the target site supports: send an authorization header or another custom header, pass cookies from a valid signed-in session, or configure a site you control to allow ScreenshotOne’s servers through its authentication or firewall. The request still needs valid authorization, and the site must allow the rendering request. These methods are for pages you own or are authorized to access; they do not bypass a site’s access controls.

This guide covers the practical decision, runnable requests, credential handling, common failure causes, and operational tradeoffs. For general screenshot capture, see ScreenshotNeo; its API documentation describes a separate screenshot API and MCP server.

1. Choose the authentication method

Method	Use it when	What you need	Main consideration
Authorization or custom header	The site accepts a token or basic authentication in a request header.	A supported authorization value, or the site’s required header name and value.	The target application must authenticate the rendering request from headers.
Cookies	The site uses a browser session cookie after sign-in.	Valid cookie names and values, with applicable domain and path attributes.	Session cookies expire and must be obtained safely. The site must allow automation.
Site-side access configuration	You control the site and can change its authentication or firewall configuration.	The ability to configure the site and its server or firewall.	ScreenshotOne describes this as a complicated, site-side configuration approach.

Start with the target site’s authentication design and your authority to change it. If a supported token header works, it is usually the most direct request configuration. Use cookies when the page specifically depends on an existing signed-in browser session. Consider firewall or access changes only when you control the site and can maintain that configuration.

2. Send an authorization header

ScreenshotOne documents an authorization option for basic authentication or a token. If the application expects a differently named header, use the general headers option. Replace the placeholders below with values issued for a site and account you are permitted to access. Do not put real secrets in published code.

curl -G 'https://api.screenshotone.com/take' \
  --data-urlencode 'access_key=YOUR_SCREENSHOTONE_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com/private/dashboard' \
  --data-urlencode 'authorization=Bearer YOUR_TARGET_SITE_TOKEN' \
  -o dashboard.png

The API key identifies your ScreenshotOne account; the authorization value is for the target site. Keep them separate and secret. For a site that expects a custom header name, configure the general headers option according to the ScreenshotOne options reference. Header names and values must match what the target application expects.

3. Pass cookies from a valid signed-in session

Use this method only when you can obtain a valid session for the target account and the site permits the automated request. Cookie acquisition may require your own sign-in code. Capture the cookie attributes the site needs, including its domain and path, and pass the relevant name and value through the API’s cookies option. Do not copy a session cookie into source control, a public example, or an issue report.

For a simple request, repeated cookie parameters can be URL-encoded. A structured POST request is often easier to maintain when cookie values contain special characters and can reduce accidental exposure through URL logs. Follow the current ScreenshotOne options reference for the exact request shape supported by your account and client.

curl 'https://api.screenshotone.com/take' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_key": "YOUR_SCREENSHOTONE_ACCESS_KEY",
    "url": "https://example.com/private/dashboard",
    "cookies": [
      {
        "name": "SESSION_COOKIE_NAME",
        "value": "YOUR_SESSION_COOKIE_VALUE",
        "domain": "example.com",
        "path": "/"
      }
    ]
  }' \
  -o dashboard.png

Use the cookie’s actual scope rather than assuming / or the parent domain. A cookie scoped to a different host or path may not be sent to the dashboard. If the session expires, sign in again through an authorized flow and update the cookie securely.

4. Configure access on a site you control

If the page is yours but it cannot authenticate with a supported header or session cookie, ScreenshotOne documents configuring the site to allow its servers through authentication or a firewall. This requires site-side access and server configuration; it is not a ScreenshotOne request parameter that automatically grants access. Review the site’s own security controls, apply the narrowest appropriate rule, and verify that normal authentication remains protected. The source material does not provide a universal firewall rule because the right configuration depends on the site.

5. Use HTTPS and protect credentials

Call the HTTPS API endpoint. ScreenshotOne’s getting-started guidance warns that HTTP does not encrypt API keys, authorization headers, cookies, or other sensitive request data in transit.
Store the ScreenshotOne access key and target-site credentials in environment variables or a secrets manager. Do not commit them to source control.
Avoid exposing unsigned screenshot URLs containing an access key in public pages, client-side code, logs, or analytics. ScreenshotOne documents sending the key in a query string, JSON body, or X-Access-Key header; choose a form appropriate to your transport and logging setup.
Restrict who can read request logs and job configuration if those systems may contain headers or cookies. Redact secrets before sharing diagnostic output.
Use credentials with only the access needed for the capture, and rotate them according to your organization’s credential practices.

ScreenshotOne says requests without caching, storage, or similar options are rendered and returned without being stored on its infrastructure. There are qualifications: a JSON response temporarily stores the screenshot to serve its URL, and rendered content can pass through temporary internal components such as queues or buffers. Check the current caching documentation and options you enable before deciding whether the handling fits your data requirements.

6. Troubleshoot failed authenticated captures

Symptom	Likely cause	What to check
Screenshot shows the login page	The target site did not accept the supplied credential, or the required cookie/header was not sent.	Verify the authentication method, header spelling and format, cookie name/value, cookie domain and path, and whether the session has expired.
Header authentication works in a browser but not in the capture	The browser flow may add a different header or obtain a token through a prior step.	Inspect the site’s documented authentication flow. Supply the required supported header; use the general headers option for a different header name.
Cookie request is redirected to sign-in	The cookie is invalid, expired, scoped to another host/path, or the target site requires additional session state.	Obtain a fresh authorized session, include the relevant cookie attributes, and confirm the request URL matches its domain and path scope.
Access denied or blocked request	The site rejects the rendering request or blocks automation.	Confirm you are authorized and that the site permits automation. If you control it, evaluate site-side access or firewall configuration; do not attempt to evade controls on a site you do not control.
Request fails before the page renders	The ScreenshotOne access key may be missing or invalid, or request parameters may be malformed.	Check the API key placement and encoding, endpoint, URL, and request format. Keep the API key distinct from the target site’s credential.
Cookie or header breaks after deployment	Credential rotation, session expiry, or an environment-specific configuration change.	Check secret injection and rotation, refresh the session through your authorized process, and avoid hard-coding credentials in the deployed application.

When diagnosing, first determine whether the request reached the target page and which authentication mechanism the page expects. Change one credential or scope setting at a time, and never paste live tokens or cookies into public support channels.

7. Reliability, performance, and cost considerations

Reliability

An authenticated screenshot is only as reliable as the credentials and the site’s authorization behavior. Session cookies expire; tokens can be revoked or rotated; and a site can change its login flow or automation policy. Build credential refresh and failure handling around the authentication lifecycle that the site actually supports. The reviewed ScreenshotOne documentation does not provide a success-rate guarantee for these methods.

Performance

Authentication adds work when the capture depends on a sign-in sequence or site-side access checks. Passing a credential for a page that already accepts it avoids implementing a browser sign-in flow in your own integration, but page rendering time still depends on the target site. The reviewed documentation provides no benchmark for authenticated capture latency, so measure your own page and request path.

Cost and output handling

Check ScreenshotOne’s current plan and billing documentation for applicable request costs; the research material does not establish a price or a billing outcome for each failure case. Also account for any caching, storage, or JSON response behavior you configure. A direct rendered response and a JSON response that serves an image URL can have different storage handling, as described in the caching documentation.

8. Or skip the browser setup

If you do not need ScreenshotOne-specific authenticated access and simply want a screenshot of a public or otherwise accessible page, ScreenshotNeo’s API docs show a one-call screenshot API. ScreenshotNeo accepts an access key and target URL and can return PNG, JPEG, WebP, or PDF output.

curl -G 'https://api.screenshotneo.com/v1/shot' \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as f:
    f.write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

9. Frequently asked questions

Can I use this to capture a page in someone else’s private account?

Only if you have authorization and the account owner or site permits the capture. These methods pass credentials the site already accepts; they do not grant permission or bypass access controls.

No. The page must accept the supplied valid session state, and automation must be allowed. Some flows require custom sign-in code or additional session data.

Should I put basic-auth credentials in the page URL?

Only if the target site specifically supports that method. Treat URL credentials as secrets because URLs can appear in logs and other systems. The authenticated-pages guide foregrounds headers, site-side access configuration, and cookies.

Are screenshots always retained by ScreenshotOne?

No universal retention claim follows from the documentation. Requests without caching, storage, or similar options are described as rendered and returned without infrastructure storage, with temporary processing and JSON-response qualifications. Review the options used for your request.