Reuse an authenticated session

When to use this

Use this when a recurring job needs an authenticated browser without logging in on every run. Browserbase contexts retain site data; a deterministic protected-page marker proves authentication. Use ordinary locators for a login form you own. Stagehand is useful when adapting the fill steps to an unfamiliar form.

Browser	Languages	Output
Browserbase	TypeScript, Python, Go	Persisted context and `out/login.json`

Goal and output

Log into the public Internet test site, persist its cookies in a Browserbase context, and reuse that context on the next run. Each run writes out/login.json with an authentication check, a reuse flag, and the Browserbase session ID.

Agent prompt

Adapt persisted login to an application I own.

Prerequisites and inputs

Add BROWSERBASE_API_KEY and OPENAI_API_KEY to .env.
BROWSERBASE_CONTEXT_ID is optional. If it is unset, the example creates a Browserbase context and prints its ID. Save that ID in .env before the reuse run.
The example includes the test site’s public LOGIN_USER and LOGIN_PASSWORD. Use credentials for your own account when adapting it.
TypeScript requires Node.js 22.18+ and pnpm. Python requires Python 3.11+ and uv. Go requires Go 1.26+.

Check out and run

Check out packages/examples/cookbooks/persisted-login using the overview command.

TypeScript
Python
Go

cd packages/examples/cookbooks/persisted-login/typescript
cp .env.example .env
pnpm install --frozen-lockfile
# First run: authenticates and persists context
pnpm start

# Second run: verifies context reuse
pnpm start

cd packages/examples/cookbooks/persisted-login/python
cp .env.example .env
uv sync --locked
# First run: authenticates and persists context
uv run --locked python main.py

# Second run: verifies context reuse
uv run --locked python main.py

cd packages/examples/cookbooks/persisted-login/go
cp .env.example .env
set -a; . ./.env; set +a
# First run: authenticates and persists context
go run .

# Second run: verifies context reuse
go run .

Fill in .env before the first run. Run sequentially so context persistence finishes before reuse.

How the job works

Open a persisted context

Launch a five-minute cloud session with the supplied or auto-created context and persist: true.

Check protected-page access

Visit the protected page. If its logout marker exists, reuse the authenticated context without model calls.

Otherwise, fill username and password through %variable% placeholders and click Login once. Check protected-page access again.

Verify and close

Write the receipt only after authentication is verified. Close Stagehand and the browser, which persists browser data for the next session.

const browser = await browserbase.launch({
  apiKey,
  timeout: 300,
  browserSettings: { context: { id: contextId, persist: true } },
});

const reused = (await page.locator('a[href="/logout"]').count()) > 0;
if (!reused) {
  await stagehand.act("Type %password% into the password field", {
    page, variables: { password },
  });
}

browser = await browserbase.launch(
    api_key=api_key, timeout=300,
    browser_settings=BrowserbaseBrowserSettings(
        context={"id": context_id, "persist": True},
    ),
)
reused = await page.locator('a[href="/logout"]').count() > 0

persist, timeout := true, float64(300)
browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
    APIKey: apiKey, Timeout: &timeout,
    BrowserSettings: &stagehand.BrowserbaseBrowserSettings{
        Context: &stagehand.BrowserbaseContext{ID: contextID, Persist: &persist},
    },
})
if err != nil { return err }
loginCount, err := page.Locator(`a[href="/logout"]`).Count(ctx)
if err != nil { return err }
reused := loginCount > 0

The excerpts show context configuration and the authentication probe. The runnable folder fills both credentials, submits once, verifies protected-page access, and closes the browser to persist the context.

Expected result and failure checks

The first run reports authentication. The second reports context reuse and writes reused: true. Both print a session link for inspection.

Failure	Check
Wrong password	Run with a fresh context and an invalid password; authentication must fail
Context reuse fails	Wait for the first run to close, then check the project and context ID
Session expires	Start a new run with the same context; do not retry login in a loop
Target requires MFA	Add an explicit application approval flow before adapting this recipe

Context IDs carry authenticated state. Treat them as credentials, keep them out of version control, and use separate contexts per account and environment.

Run one writer per Browserbase context. Wait for browser closure and persistence before starting the next session.

For local profile persistence, see user data.

Adapt to your site

Change the fixed login URL, protected URL, and authenticated marker together. The marker must prove access to a protected page, not merely the presence of a generic header. Keep credentials in variables and serialize writes to each context. Add an explicit MFA flow when your application requires it. Browser data persistence and form approval.

First steps

The basics

Configuration

Add-ons

Integrations

Best practices

Cookbooks

Migration guide

SDK reference

Reuse an authenticated session

When to use this

Goal and output

Agent prompt

Prerequisites and inputs

Check out and run

How the job works

Expected result and failure checks

Adapt to your site

​When to use this

​Goal and output

​Agent prompt

​Prerequisites and inputs

​Check out and run

​How the job works

​Expected result and failure checks

​Adapt to your site

​Related

When to use this

Goal and output

Agent prompt

Prerequisites and inputs

Check out and run

How the job works

Expected result and failure checks

Adapt to your site

Related