How to Use Urlbox to Screenshot Pages Behind Basic Authentication
Pass HTTP Basic Authentication credentials to Urlbox as a destination Authorization header, then capture the page as a screenshot.
To use Urlbox to screenshot a page protected by HTTP Basic Authentication, Base64-encode the complete username:password pair and pass it as the destination page’s Authorization: Basic … header using Urlbox’s header render option. Authenticate separately to the Urlbox API with your Urlbox project secret as a Bearer token. The destination credentials and the Urlbox API secret serve different purposes.
1. Confirm the page uses HTTP Basic Authentication
HTTP Basic Authentication usually triggers the browser’s built-in username-and-password prompt. If the page instead displays a login form, it likely uses a form-based session; after logging in, the site expects a session cookie, so sending a Basic Authorization header may not work.
Use this method only for a page and credentials you are authorized to access. If you control the target site and can choose its authentication mechanism, Urlbox’s guide recommends a rotating temporary token in an Authorization header when possible. Avoid putting credentials in URL parameters, which can be logged. Use HTTPS and protect both your destination credentials and Urlbox secret.
2. Encode the destination credentials
Join the username and password with a colon, then Base64-encode that entire string, including the colon. For example, foo:bar encodes to Zm9vOmJhcg==, making the destination header value Basic Zm9vOmJhcg==.
Base64 is an encoding, not encryption. Do not treat the encoded value as secret protection. Avoid committing credentials to source control or printing them in logs.
3. Send a synchronous render request
Urlbox’s official example uses https://api.urlbox.com/v1/render/sync and passes the destination header as a render option in the JSON body. Replace the example destination, username, password, and API secret with values for your authorized target. The example’s foo and bar credentials are illustrative only.
curl -X POST "https://api.urlbox.com/v1/render/sync" \
-H "Authorization: Bearer YOUR_URLBOX_SECRET" \
-H "Content-Type: application/json" \
-d '{
"url": "https://httpbin.org/basic-auth/foo/bar",
"full_page": true,
"header": "Authorization=Basic Zm9vOmJhcg=="
}' \
-o screenshot.pngThe request has two authentication layers:
Authorization: Bearer YOUR_URLBOX_SECRETauthenticates your request to Urlbox.header: "Authorization=Basic …"tells Urlbox to send the Basic credentials to the destination page.
Keep the API secret out of client-side code and public repositories. The documented header render option currently requires a HiFi plan; confirm that the Urlbox account you use is entitled to it.
4. Generate the header safely
For repeatable captures, generate the Base64 value from environment variables rather than typing credentials into a script. This Python example builds the destination header and makes the synchronous request. It assumes the Urlbox endpoint returns the rendered image response, as in the documented synchronous pattern.
import base64
import os
import requests
username = os.environ["TARGET_USERNAME"]
password = os.environ["TARGET_PASSWORD"]
urlbox_secret = os.environ["URLBOX_SECRET"]
pair = f"{username}:{password}".encode("utf-8")
encoded = base64.b64encode(pair).decode("ascii")
response = requests.post(
"https://api.urlbox.com/v1/render/sync",
headers={
"Authorization": f"Bearer {urlbox_secret}",
"Content-Type": "application/json",
},
json={
"url": "https://your-authorized-site.example/private-page",
"full_page": True,
"header": f"Authorization=Basic {encoded}",
},
timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image:
image.write(response.content)Set TARGET_USERNAME, TARGET_PASSWORD, and URLBOX_SECRET in your process environment or secret manager. Use the real page URL you are authorized to capture.
5. Choose full-page capture behavior
Set full_page to true when you need the entire document rather than the initial viewport. Urlbox documents two full-page modes:
stitchis the default and is designed for accuracy.nativeis faster, but may not work well across all sites.
Start with the default stitch behavior when completeness matters. Consider native mode when capture speed matters and verify that the target page renders correctly. Full-page captures can take longer and produce larger files than viewport captures, especially on long pages.
6. If the site uses a login form, send its session cookie
A normal login page is not HTTP Basic Authentication. A successful form login commonly creates a session cookie; the screenshot request needs the relevant cookie rather than a Basic header. Urlbox documents a cookie option for sending cookies with the destination request. Log in through the site’s supported flow, obtain the necessary session cookie securely, and configure the cookie option according to the current Urlbox render-options documentation.
Session cookies can expire, be scoped to a domain or path, or require additional cookies. Do not copy a session cookie into a shared script or log. If the site supports a token or Authorization header, use that only in the way the site documents.
7. Troubleshoot common failures
| Symptom | Likely cause | What to check |
|---|---|---|
| The page shows an authentication prompt or an unauthorized response | The destination header is missing, malformed, or contains the wrong credentials. | Encode username:password as one string, including the colon; prefix it with Basic ; confirm the header render option is accepted by the account plan. |
| Urlbox rejects the API request as unauthorized | The Urlbox API secret is absent or invalid. | Check the API request’s Authorization: Bearer … header. Do not put the destination Basic value there. |
| Basic authentication works in a browser but the screenshot is logged out | The site may use a login form and cookie session rather than HTTP Basic Authentication. | Determine the site’s actual authentication flow and use the documented cookie option for a valid session. |
| The header option is unavailable or rejected | The account may not include the required plan entitlement. | Urlbox currently lists the header option as requiring a HiFi plan; confirm current account access in Urlbox documentation. |
| The screenshot is incomplete or blank | The page may not have loaded successfully, may need more time, or may behave differently during full-page capture. | Check the destination URL and authorization first. Compare the default stitch mode with native mode only if speed is important; native may not suit every site. |
| The image file is not a usable screenshot | The request may have returned an error response that was saved as an image. | Inspect the HTTP status and response content type before saving in production; surface response errors instead of treating every body as an image. |
| Credentials appear in logs or repository history | Secrets were embedded in code, command history, or request logging. | Move secrets to environment variables or a secret manager, restrict logs, and rotate exposed credentials. |
8. Reliability, speed, and cost considerations
There is no published success-rate statistic in the cited Urlbox guide, and behavior depends on the destination site and its authentication flow. Validate captures against a page you are authorized to access. For long pages, allow for a larger render and output. Stitch mode favors accuracy; native mode can be faster but may not work well on every site.
Check Urlbox’s current documentation and your account plan before building around the header option, since the documentation lists a HiFi requirement and live plan details can change. The research sources do not establish Urlbox pricing, so consult Urlbox directly for current costs.
Or skip the browser setup
If your goal is a clean capture rather than configuring a browser render, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF; see the ScreenshotNeo API documentation for request options. For an authorized public page, a basic cURL call looks like this:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes known cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. These features do not bypass a site’s access controls: use a URL and access method you are authorized to use.
Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does Base64 encrypt my password?
No. Base64 only encodes the credentials. Use HTTPS and handle the encoded value as a secret.
Can I use this for a regular username-and-password form?
Usually not with the Basic header alone. A form-based login typically relies on a session cookie; use the cookie option with a valid session.
Can I capture only the first screen?
Yes. Omit full_page or set it to false if you want a viewport capture. Use true for a full-page capture.
Are the example credentials real?
No. They illustrate the encoding format only. Supply credentials for a destination you are authorized to access.
