Use page.authenticate() only when the server uses HTTP authentication. For a typical website login form, automate the form; for an existing session, restore its cookies; and for token-based access, send the expected headers. Whichever method you use, verify a site-specific signed-in state rather than assuming that navigation succeeded.
Choose the authentication method the site uses
| Mechanism | Use it when | Credential scope | What to verify |
|---|---|---|---|
| HTTP authentication | The server challenges the request using HTTP authentication. | Credentials supplied to the challenge through Puppeteer. | A protected page or authenticated-only element is present. |
| HTML login form | The site presents a conventional username/password form. | Credentials entered into that site’s form; the site establishes its session. | A site-specific account indicator, protected URL, or private content. |
| Session cookies | You already have valid session cookies to restore. | Browser storage for the relevant domain and browser context. | The restored session reaches a protected page and shows signed-in content. |
| Authentication headers | The service explicitly expects a header such as a bearer token. | Every request initiated by the page. | The service returns the expected protected content, not an error or login page. |
These mechanisms are not interchangeable. In particular, Puppeteer documents Page.authenticate() as supplying credentials for HTTP authentication, not as a universal HTML-form login helper. The current retrieved API reference is labeled Puppeteer 25.12.0; check the documentation for the version installed in your project before relying on API details (Puppeteer Page.authenticate()).
As an Amazon Associate I earn from qualifying purchases.
HTTP authentication with page.authenticate()
Set the credentials before navigating to the protected resource. The credentials object takes string values for username and password.
Free tools Windows power users keep installed
One-click scans. No signup required.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.authenticate({
username: process.env.HTTP_AUTH_USER,
password: process.env.HTTP_AUTH_PASSWORD,
});
const response = await page.goto('https://example.com/protected', {
waitUntil: 'domcontentloaded',
});
console.log('HTTP status:', response?.status());
console.log('Page title:', await page.title());
// Replace this with a check specific to the protected site.
const signedIn = await page.locator('[data-account-menu]').count();
if (signedIn === 0) {
throw new Error('The expected authenticated account indicator was not found');
}
} finally {
await browser.close();
}Replace the URL and the example account selector with values that match the site. Keep credentials outside source control, such as in environment variables or a secrets manager. Puppeteer’s API reference warns that authentication turns request interception on behind the scenes and might affect performance. You can disable authentication by passing null when it is no longer needed (API reference; the retrieved credentials reference is labeled 25.10.0: Credentials).
#1 Best Overall
Log in through a website form
For an ordinary web application login, automate the same page interactions a user would perform. Selectors, submit behavior, multi-factor authentication (MFA), consent screens, and the success condition differ by site, so treat this as a pattern rather than a universal recipe.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com/login', { waitUntil: 'domcontentloaded' });
await page.locator('input[name="username"]').fill(process.env.APP_USER);
await page.locator('input[name="password"]').fill(process.env.APP_PASSWORD);
await page.locator('button[type="submit"]').click();
// Choose a condition that proves this site's login worked.
await page.locator('[data-account-menu]').wait();
const signedInUrl = page.url();
console.log('Signed-in page:', signedInUrl);
} finally {
await browser.close();
}Adapt the selectors to the actual form. Some sites submit without a full navigation; others redirect or require an extra step. If MFA or a consent screen appears, handle it only through an authorized workflow supported by the site. A completed click or navigation is not sufficient evidence of a successful login; test for a known authenticated indicator or protected content.
Rank #2
Restore an existing session with cookies
Use cookie restoration when you already have a valid session cookie and need to load it into the correct browser storage context before visiting the protected page. Cookie domain, path, expiry, security attributes, and browser context matter; a cookie copied from one session may be expired or unusable in another.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
try {
const context = await browser.createBrowserContext();
const page = await context.newPage();
await context.setCookie({
name: 'session_id',
value: process.env.SESSION_COOKIE,
domain: 'example.com',
path: '/',
httpOnly: true,
secure: true,
sameSite: 'Lax',
});
await page.goto('https://example.com/account', { waitUntil: 'domcontentloaded' });
// Replace with a site-specific authenticated-state check.
await page.locator('[data-account-menu]').wait();
} finally {
await browser.close();
}The cookie values and attributes above are illustrative: use the values issued by the site, not guessed values. Treat session cookies as passwords because possession may grant access to the account. Puppeteer’s cookie guide covers reading, setting, and deleting cookies: Cookies guide. The retrieved guide is on the next documentation path, while the retrieved API references have separate version labels; confirm the API and deprecation status for your installed release. The Page reference marks page-level cookie APIs deprecated and points to browser or browser-context cookie methods (Page API).
Send authentication headers when the service requires them
If the target service expects a token or other authentication header, set it before navigation. Puppeteer sends extra headers with every request initiated by the page; header names are lowercased and their order is not guaranteed. Do not use this as a generic substitute for a form login or HTTP authentication.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.setExtraHTTPHeaders({
authorization: `Bearer ${process.env.API_TOKEN}`,
});
await page.goto('https://example.com/private', { waitUntil: 'domcontentloaded' });
// Replace with a check for the expected private content.
await page.locator('[data-private-content]').wait();
} finally {
await browser.close();
}Because the configured headers apply to page-initiated requests broadly, use them only with pages and services that are supposed to receive the credentials. See Puppeteer’s setExtraHTTPHeaders() reference, retrieved with a 25.12.0 version label.
Rank #4
Verify the authenticated state, not just the navigation
Use a check tied to the target site’s expected signed-in state: an account menu, a known authenticated URL, or content only available after login. A navigation response or request completion alone does not prove that authentication succeeded. Puppeteer’s request documentation notes that HTTP errors such as 404 and 503 still count as successfully completed requests, and redirects cause a subsequent request (HTTPRequest reference).
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall- Check the final URL for an unexpected return to the login page.
- Check an authenticated-only element or content marker.
- Inspect the response status and page content for access-denied or error states.
- Fail the automation explicitly if the site-specific success condition is absent.
Troubleshooting common failures
The page still shows a login form
- Likely cause: The code used HTTP authentication for a site that requires an HTML form, or the form selectors did not match the page.
- Fix: Identify the actual mechanism, automate the form when appropriate, and verify a site-specific signed-in indicator.
Credentials appear correct but the protected page is unavailable
- Likely cause: Credentials do not match the server’s HTTP challenge, or the server expects a different authentication scheme.
- Fix: Confirm the mechanism and credential format with the service owner, then test the protected destination and its content rather than relying on a successful navigation event.
A restored cookie does not create a session
- Likely cause: The cookie is expired, belongs to another domain or path, has incompatible attributes, or was added to a different browser context than the page uses.
- Fix: Use a valid cookie issued for the target site, set it in the context that will open the page, and confirm the site accepts the session. Do not publish or log cookie values.
Header-based authentication fails or leaks beyond the intended request
- Likely cause: The endpoint does not expect that header, the token is invalid, or a page-wide extra header is being sent more broadly than intended.
- Fix: Confirm the service’s documented header requirements and scope the page and requests so credentials are sent only where intended.
Automation seems slower after enabling HTTP authentication
- Likely cause: Puppeteer’s documented implementation turns on request interception behind the scenes for
page.authenticate(), which might affect performance. - Fix: Use HTTP authentication only when the server requires it, and disable it with
page.authenticate(null)after the protected requests if the remainder of the workflow no longer needs it.
Or skip the browser setup
If your task is to produce a screenshot of a publicly accessible page rather than automate a private login flow, ScreenshotNeo can return a screenshot or PDF from one GET request. It is not a way to bypass a login or access a private account.
Example request and options are documented at ScreenshotNeo docs.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp- Cookie banners, newsletter popups, and chat widgets are removed before capture; each of those steps can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents and MCP clients. - The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does page.authenticate() fill in a website login form?
No. It supplies credentials for HTTP authentication. A conventional HTML login form requires site-specific page interactions.
Does a successful page.goto() prove that authentication worked?
No. Check a site-specific authenticated indicator, protected URL, or private content.
Can I reuse a session cookie in Puppeteer?
Yes, if it is valid and installed in the appropriate browser context with the attributes required by the target site.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
