Puppeteer Credentials: Set HTTP Authentication Credentials

To set HTTP authentication credentials in Puppeteer, call await page.authenticate({ username, password }) before navigating to the protected URL. The method applies to that Page and handles HTTP authentication challenges; it does not document filling in a website’s ordinary HTML login form.

const page = await browser.newPage();
await page.authenticate({
  username: 'user',
  password: 'pass',
});
await page.goto('https://example.com/protected');

1. What page.authenticate() does

Puppeteer’s Page.authenticate(credentials) provides credentials for HTTP authentication and returns a promise. The documented credential fields are string properties named username and password. Puppeteer enables request interception behind the scenes to implement authentication, which may affect performance; the documentation does not quantify the impact. [Puppeteer Page.authenticate API] [Puppeteer Credentials interface]

A Page represents a tab or extension background page. Set credentials on each page that needs them; this is not browser-wide configuration. [Puppeteer Page API]

2. Set credentials before navigation

Install Puppeteer in a Node.js project, then create a page, authenticate it, and navigate to the protected resource. Await each asynchronous operation so authentication is configured before the request starts.

npm install puppeteer

const puppeteer = require('puppeteer');

async function main() {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.authenticate({
      username: process.env.HTTP_AUTH_USERNAME,
      password: process.env.HTTP_AUTH_PASSWORD,
    });

    const response = await page.goto('https://example.com/protected', {
      waitUntil: 'domcontentloaded',
      timeout: 30000,
    });

    console.log('HTTP status:', response ? response.status() : 'no response');
    console.log('Page title:', await page.title());
  } finally {
    await browser.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Set HTTP_AUTH_USERNAME and HTTP_AUTH_PASSWORD in the process environment before running the script. Avoid putting real secrets directly in source code, command history, or logs. This example uses CommonJS and the Puppeteer package; if your project uses ES modules, import Puppeteer with import puppeteer from 'puppeteer'; and keep the same awaited calls.

Handle a failed navigation

page.goto() can fail because of a timeout or network error, so catch failures at the task boundary. An HTTP response with an error status is different: navigation can complete and return a response whose status() is, for example, 401 or 403. Check the response and the resulting page rather than assuming that a resolved navigation means authentication succeeded.

const response = await page.goto(url, { waitUntil: 'domcontentloaded' });
if (!response) {
  throw new Error('Navigation did not return an HTTP response');
}
if (response.status() === 401) {
  throw new Error('The server still requires valid HTTP authentication');
}
if (!response.ok()) {
  throw new Error(`Navigation returned HTTP ${response.status()}`);
}

3. Credential and scope details

Question	Behavior
Required object	Pass an object with string username and password values.
When to call	Call and await page.authenticate() before navigating to the protected resource.
Scope	Credentials are set on the individual Puppeteer Page.
Disable authentication	Call await page.authenticate(null).
Implementation note	Request interception is enabled behind the scenes and may affect performance.

These are the API’s documented behavior and caveat. [Puppeteer Page.authenticate API] [Puppeteer Credentials interface]

Turn authentication off

Pass null to disable the configured authentication for that page. Await the call before continuing with later navigation.

await page.authenticate(null);
await page.goto('https://example.com/');

HTTP authentication is not a form login

HTTP authentication is a browser-level challenge from the server. A website login form is HTML rendered by the page, and its fields and submission flow are application-specific. The API reference documents HTTP authentication, not form filling. For a form, inspect the page’s actual controls and use Puppeteer’s locator or selector APIs to fill and submit them; then handle the site’s session, redirects, and any additional verification separately.

4. Proxy authentication and separate credentials

page.authenticate() can be used for HTTP authentication challenges, including proxy authentication, but a single configured username/password pair cannot express different credentials for a proxy challenge and a website challenge at the same time. This edge case is described in a supplementary Puppeteer guide, rather than guaranteed by the official API reference. [Official Page.authenticate API] [Supplementary proxy-authentication guide]

If both the upstream proxy and the website require different credentials, one suggested architecture is to put a local proxy in front of the upstream proxy and let that local proxy handle the upstream proxy credentials, leaving the page’s authentication pair available for the website. Validate the architecture against your proxy and Puppeteer versions.

5. Troubleshooting

Symptom	Likely cause	What to check or change
The server still shows an authentication challenge or returns 401	Credentials are wrong, belong to a different realm, or the target is not using the expected HTTP authentication scheme.	Confirm the username and password with the site or service owner. Check the response status and whether authentication is required on the URL actually requested after redirects.
The protected page is not reached	Authentication was configured after navigation, or the call was not awaited.	Call await page.authenticate(...) before page.goto().
A login page still appears	The site may use an HTML form or application session instead of HTTP authentication.	Use the site’s form flow and session requirements; authenticate() is documented for HTTP authentication challenges.
Proxy access fails while site access succeeds, or vice versa	The proxy and website may require different credential pairs.	One page authentication pair cannot express both pairs simultaneously. Consider a local proxy to handle upstream proxy credentials, then configure website credentials on the page.
Navigation times out	The server, network, proxy, or page load may be slow or stalled.	Check connectivity and proxy settings, inspect the navigation error, and choose a wait condition appropriate to the page. Increase the timeout only when the expected response time warrants it.
Automation becomes slower after adding authentication	Puppeteer enables request interception behind the scenes for authentication.	Measure the effect in your own workload. Avoid claiming a fixed overhead: the API documentation gives no benchmark.
Credentials are undefined	Environment variables were not set in the process running the script.	Check variable names and deployment configuration without printing secret values to logs.

6. Performance, reliability, and cost

Puppeteer warns that the request interception used to implement authentication might affect performance. The amount depends on the run and is not quantified in the API documentation, so measure with the same pages, network, and concurrency you expect in production. Keep authentication setup limited to pages that need it, and reuse the browser according to your application’s lifecycle rather than launching a new browser for every page.

For reliability, configure authentication before navigation, keep secrets outside source control, handle both navigation exceptions and HTTP error responses, and test redirects and protected subresources when they matter to the task. HTTP authentication for the main document does not prove that every later resource or application flow will succeed.

Puppeteer is a library; its API reference does not set a per-screenshot charge. Your operational costs come from running the browser and its infrastructure, and vary by deployment. If the task is simply to obtain a website screenshot and you do not need a custom browser workflow, an API can avoid managing browser setup.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its API parameters used by other screenshot APIs also work. The example below requests a WebP screenshot; see the ScreenshotNeo API documentation for the request options and response details.

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()
open("shot.webp", "wb").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: HTTP ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', image);

• Cookie and consent banners are accepted and removed before capture, along with 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Responses include X-Page-Verdict and X-Billed headers.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.
• The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan.

Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.

8. FAQ

Does page.authenticate() work for every kind of HTTP authentication?

The API documents credentials for HTTP authentication but does not enumerate scheme-specific compatibility. Check the target server’s requirements if its challenge is not accepted.

Can I use different credentials for each tab?

Authentication is configured on a Page, so configure each page that needs its own credentials.

Does authentication guarantee that a page is safe to capture?

No. It supplies credentials for an HTTP challenge. You still need to confirm the response, page content, and any application-specific access requirements.