How to Take Screenshots of Password-Protected Pages with ScreenshotAPI

To screenshot a password-protected page with ScreenshotAPI, first identify how the site authenticates: HTTP Basic Auth, a session cookie, or a custom request header. Send the matching credential in a POST request, then check the final page status. A returned image can show a login page; a reported 401 or 403 means the capture did not reach the protected content.

ScreenshotAPI documents basic_auth, cookies, and target-host headers for authenticated captures. The options are not interchangeable: use the one the target site expects. [ScreenshotAPI documentation] [ScreenshotAPI help]

1. Identify the page’s authentication method

Determine which authentication mechanism protects the exact URL you want to capture:

• HTTP Basic Authentication: the origin asks for a username and password, often through a browser authentication dialog. Use basic_auth.
• Session cookie: a browser that has already signed in sends a session cookie with requests. Use cookies containing a valid cookie for the target host.
• Custom request header: a staging or preview site may require a header such as an access token. Use header or the documented headers object in the POST form.
• Interactive sign-in flow: a page may require form submissions, JavaScript challenges, multi-factor authentication, or other browser state. A credential field does not complete every interactive login. Confirm what the site supports before relying on a server-side capture.

If the page is available only in a browser session on your own machine, a hosted renderer cannot automatically inherit that local session. The ScreenshotAPI documentation points to a local browser capture workflow for that case.

2. Send credentials in a POST request

Use POST when a request contains authentication material. ScreenshotAPI warns that query strings may be recorded in access logs; credentials in a JSON body stay out of the URL. Keep them in trusted server-side code and out of client-side page source. The target-host custom headers are scoped to requests for that host and do not follow a redirect to another host. [ScreenshotAPI documentation]

The following examples show the request shape and the three documented authentication inputs. Replace the placeholder values with credentials you are authorized to use. Check the current ScreenshotAPI documentation for the exact endpoint, required API key field, and response format for your account.

HTTP Basic Auth

curl -X POST "https://shot.screenshotapi.net/screenshot" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://staging.example.com/private",
    "basic_auth": {
      "username": "YOUR_TARGET_USERNAME",
      "password": "YOUR_TARGET_PASSWORD"
    }
  }' \
  -o capture.png

Session cookie

curl -X POST "https://shot.screenshotapi.net/screenshot" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://staging.example.com/private",
    "cookies": [
      {"name": "session", "value": "YOUR_SESSION_VALUE"}
    ]
  }' \
  -o capture.png

Custom header

curl -X POST "https://shot.screenshotapi.net/screenshot" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://staging.example.com/private",
    "headers": {
      "X-Preview-Token": "YOUR_PREVIEW_TOKEN"
    }
  }' \
  -o capture.png

These examples illustrate the documented JSON fields; they are not a guarantee that every ScreenshotAPI account accepts this illustrative endpoint or every field combination. Use the endpoint and request schema in the current first-party docs. Include only the authentication method that the target requires.

3. Verify that the capture reached the protected content

Do not treat successful image bytes as proof of successful authentication. Inspect ScreenshotAPI’s reported final-page HTTP status and, where available, the response metadata. Its documentation states that a 401 or 403 means the image is a login or error page, not the intended content. [ScreenshotAPI documentation]

1. Make a capture request using the correct authentication mechanism.
2. Read the final-page status reported by the API.
3. If the status is 401 or 403, treat the result as an authentication failure even if an image was returned.
4. If the status indicates success, inspect the image for the expected page content. A successful status alone cannot confirm that the expected account or page state was selected.

4. Troubleshooting

Symptom	Likely cause	What to check
Image shows a login page; final status is 401	Basic Auth credentials are missing or incorrect, or the target uses another authentication method.	Confirm that the URL prompts for HTTP Basic Auth. Correct the username and password, or switch to the actual cookie or header method.
Image shows an access-denied page; final status is 403	The target rejected the request or the credential does not grant access.	Confirm the credential is valid for this resource and that the site permits the request. Do not assume a screenshot API can bypass access controls.
Cookie request still shows a logged-out page	The session cookie may be expired, incomplete, or not applicable to the target host.	Use a current cookie for the correct host and confirm that the site relies on that cookie for the session. Avoid sending unrelated browser cookies.
Custom header works on the first URL but not after redirect	ScreenshotAPI documents target-host header scope; the header is not forwarded to a different host.	Check the redirect destination and whether it requires its own supported authentication setup.
Login flow needs a form, MFA, or browser-only state	The page uses an interactive flow beyond the documented credential inputs.	Check whether the site offers a supported session-cookie or header path. If access exists only in a local browser session, use a local browser capture workflow.
Credentials appear in logs or monitoring	They may have been sent in a URL or exposed in client-side code.	Use POST body fields, keep secrets in trusted server-side code, and rotate exposed credentials.

5. Security, reliability, and operating cost

• Protect credentials: POST avoids placing secrets in the URL, but it does not make credentials safe to expose elsewhere. Store them server-side, restrict access, and avoid logging request bodies.
• Minimize session scope: send only the cookie or header needed for the target. Treat session cookies as credentials because they can grant access to the account.
• Handle expiry: cookies and tokens can expire or be revoked. Detect authentication failures from the final status and refresh credentials through the site’s authorized process.
• Validate the result: preserve the final status alongside the image in automated workflows. A login page screenshot is a technically valid image but usually a failed capture for the intended task.
• Account for redirects: verify the destination host and its authentication needs, particularly when using custom headers.
• Cost: the research sources provide no pricing or performance figures for ScreenshotAPI, so check its current pricing and limits before estimating recurring capture costs.

6. When a local browser is the better fit

Use a local browser workflow when the protected content depends on an already-authenticated browser on your machine, or on an interactive login state that the documented server-side inputs do not represent. This keeps the session in the environment where it already exists. For automated server-side capture, first confirm the site’s authentication method and use only the matching supported credential input.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Its API accepts one GET request with a URL and returns a PNG, JPEG, WebP, or PDF. For a URL that is publicly reachable by the capture service, the basic call is:

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

See the ScreenshotNeo API docs for request options and access-key setup. The ScreenshotNeo facts provided for this article do not specify authenticated-page capture inputs, so do not put protected-page credentials into this example; confirm support in the docs for your exact authentication setup.

• Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; responses identify the page verdict and billing status in headers.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
• The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots. All features are on every plan.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

FAQ

Can ScreenshotAPI take a screenshot behind any login?

No single credential input covers every login. The documented inputs are Basic Auth, cookies, and custom headers; interactive or browser-local authentication may need a different workflow.

Does receiving an image mean authentication succeeded?

No. Check the final-page status and inspect the image. A 401 or 403 indicates a login or error page.

Should I put a password or session token in the URL?

No. Use a POST body for credentials because URLs can be recorded in logs, and keep secrets in trusted server-side code.

Can I use a custom header across a redirect to another domain?

ScreenshotAPI documents custom headers as target-host scoped; they do not follow redirects to another host.