Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

docs: auth overview

Laith Weinbergerb157775d8225
diff --git a/docs/customize/browser/authentication.mdx b/docs/customize/browser/authentication.mdx
new file mode 100644
index 000000000..116975c25
--- /dev/null
+++ b/docs/customize/browser/authentication.mdx
@@ -0,0 +1,340 @@
+---
+title: "Authentication"
+description: "Login to websites using real browser profiles, storage state, and 2FA codes"
+icon: "key"
+mode: "wide"
+---
+
+Browser-Use supports multiple authentication strategies depending on your use case:
+
+| Approach | Best For | Setup Effort |
+|----------|----------|--------------|
+| [Real Browser](#real-browser-profiles) | Personal automation, existing logins | Low |
+| [Storage State](#storage-state-persistence) | Production, CI/CD, headless | Medium |
+| [TOTP 2FA](#totp-2fa) | Sites with authenticator apps | Low |
+| [Email and SMS 2FA](#email-and-sms-2fa) | Sites with email/SMS verification | Medium |
+
+---
+
+## Real Browser Profiles
+
+Connect to your existing Chrome browser to reuse your authenticated sessions. No need to handle logins, cookies, or 2FA - if you're logged in on Chrome, the agent is, too.
+
+<Info>
+See [Real Browser](/customize/browser/real-browser) for more details and platform paths.
+</Info>
+
+<Warning>
+You may need to close Chrome completely before running. Browser-Use launches Chrome in debug mode, which can conflict with existing Chrome processes.
+</Warning>
+
+```python
+from browser_use import Agent, Browser, ChatOpenAI
+
+# Auto-detect Chrome and profile (cross-platform)
+browser = Browser.from_system_chrome()
+
+agent = Agent(
+ task='Check my Gmail inbox',
+ browser=browser,
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+)
+await agent.run()
+```
+
+---
+
+## Storage State Persistence
+
+Export cookies and localStorage from an authenticated browser, then load them in headless mode. Useful for production/CI where you can't use a real browser profile.
+
+<Info>
+See [Browser Parameters](/customize/browser/all-parameters#user-data--profiles) for all storage options.
+</Info>
+
+### Export from Real Browser
+
+```python
+from browser_use import Browser
+
+browser = Browser.from_system_chrome()
+await browser.start()
+await browser.export_storage_state('auth.json')
+await browser.stop()
+```
+
+### Load in Headless Mode
+
+```python
+from browser_use import Agent, Browser, ChatOpenAI
+
+browser = Browser(storage_state='auth.json')
+
+agent = Agent(
+ task='Check my notifications',
+ browser=browser,
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+)
+await agent.run()
+```
+
+### Auto-Save and Load
+
+When you provide a `storage_state` path, Browser-Use automatically:
+- Loads cookies from the file on startup (if it exists)
+- Saves cookies to the file periodically and on shutdown
+
+```python
+browser = Browser(storage_state='session.json')
+```
+
+The file is created if it doesn't exist, and new cookies are merged with existing ones on each save.
+
+### Storage State Format
+
+The JSON file follows Playwright's format:
+
+```json
+{
+ "cookies": [
+ {
+ "name": "session_id",
+ "value": "abc123",
+ "domain": ".example.com",
+ "path": "/",
+ "expires": 1704067200,
+ "httpOnly": true,
+ "secure": true,
+ "sameSite": "Lax"
+ }
+ ],
+ "origins": [
+ {
+ "origin": "https://example.com",
+ "localStorage": [
+ {"name": "auth_token", "value": "xyz789"}
+ ]
+ }
+ ]
+}
+```
+
+---
+
+## TOTP 2FA
+
+For sites using authenticator apps (Google Authenticator, 1Password, etc.), Browser-Use can generate TOTP codes automatically.
+
+<Info>
+See [Sensitive Data](/examples/templates/sensitive-data) for more on credential handling.
+</Info>
+
+### How It Works
+
+1. Get the TOTP secret key when setting up 2FA (usually shown as "manual entry" or "can't scan QR code")
+2. Pass the secret with `bu_2fa_code` suffix in `sensitive_data`
+3. When the agent inputs `bu_2fa_code`, it generates a fresh 6-digit code
+
+```python
+from browser_use import Agent, ChatOpenAI
+
+# TOTP secret from your authenticator setup
+# (NOT the 6-digit code - the secret key itself)
+totp_secret = 'JBSWY3DPEHPK3PXP'
+
+agent = Agent(
+ task='''
+ 1. Go to https://example.com/login
+ 2. Enter username x_user and password x_pass
+ 3. When prompted for 2FA, enter bu_2fa_code
+ ''',
+ sensitive_data={
+ 'x_user': 'myusername',
+ 'x_pass': 'mypassword',
+ 'bu_2fa_code': totp_secret, # suffix must be bu_2fa_code
+ },
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+)
+await agent.run()
+```
+
+<Tip>
+The placeholder name must end with `bu_2fa_code`. You can use any prefix: `google_bu_2fa_code`, `github_bu_2fa_code`, etc.
+</Tip>
+
+### Where to Find TOTP Secrets
+
+- **1Password**: Edit item → One-Time Password → Show secret
+- **Google Authenticator**: During setup, click "Can't scan it?" to see the key
+- **Authy**: Export via desktop app settings
+- **Most sites**: Look for "manual entry" or "setup key" during 2FA enrollment
+
+---
+
+## Email and SMS 2FA
+
+For sites that send verification codes via email or SMS, use follow-up tasks to retrieve the code.
+
+### With AgentMail
+
+[AgentMail](https://agentmail.to) provides disposable inboxes for email verification:
+
+```python
+from agentmail import AsyncAgentMail
+from browser_use import Agent, ChatOpenAI, Tools, ActionResult
+
+email_client = AsyncAgentMail()
+inbox = await email_client.inboxes.create()
+
+tools = Tools()
+
[email protected]('Get email address for signup')
+async def get_email_address():
+ return ActionResult(extracted_content=inbox.inbox_id)
+
[email protected]('Get verification code from email')
+async def get_verification_code():
+ emails = await email_client.inboxes.messages.list(inbox_id=inbox.inbox_id)
+ if emails.messages:
+ return ActionResult(extracted_content=emails.messages[0].text)
+ return ActionResult(error='No emails found')
+
+agent = Agent(
+ task='Sign up at example.com, get verification code from email',
+ tools=tools,
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+)
+await agent.run()
+```
+
+See [`examples/integrations/agentmail/`](https://github.com/browser-use/browser-use/tree/main/examples/integrations/agentmail) for a more complete implementation with email waiting and parsing.
+
+### With 1Password SDK
+
+Retrieve codes from your password manager:
+
+```python
+import os
+from onepassword.client import Client
+from browser_use import Agent, Tools, ActionResult, ChatOpenAI
+
+tools = Tools()
+
[email protected]('Get 2FA code from 1Password', domains=['*.google.com'])
+async def get_1password_2fa():
+ client = await Client.authenticate(
+ auth=os.environ['OP_SERVICE_ACCOUNT_TOKEN'],
+ integration_name='Browser-Use',
+ integration_version='v1.0.0',
+ )
+ code = await client.secrets.resolve('op://Private/Google/One-time passcode')
+ return ActionResult(extracted_content=code)
+
+agent = Agent(
+ task='Login to Google and check email',
+ tools=tools,
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+)
+await agent.run()
+```
+
+See [`examples/custom-functions/onepassword_2fa.py`](https://github.com/browser-use/browser-use/tree/main/examples/custom-functions/onepassword_2fa.py) for the full example.
+
+### With Gmail API
+
+Built-in Gmail integration for reading 2FA codes from your inbox:
+
+```python
+from browser_use import Agent, ChatOpenAI, Tools
+from browser_use.integrations.gmail import GmailService, register_gmail_actions
+
+gmail_service = GmailService()
+tools = Tools()
+register_gmail_actions(tools, gmail_service=gmail_service)
+
+agent = Agent(
+ task='Login to example.com, then get the verification code from Gmail',
+ tools=tools,
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+)
+await agent.run()
+```
+
+Requires Gmail API setup:
+1. Enable Gmail API in [Google Cloud Console](https://console.cloud.google.com/)
+2. Create OAuth 2.0 credentials (Desktop app)
+3. Save credentials to `~/.config/browseruse/gmail_credentials.json`
+
+See [`examples/integrations/gmail_2fa_integration.py`](https://github.com/browser-use/browser-use/tree/main/examples/integrations/gmail_2fa_integration.py) for setup with automatic credential validation.
+
+---
+
+## Security Best Practices
+
+<Info>
+See [Secure Setup](/examples/templates/secure) for enterprise security with Azure OpenAI.
+</Info>
+
+### Restrict Domains
+
+Limit where the browser can navigate to prevent credential leaks:
+
+```python
+browser = Browser(
+ allowed_domains=['*.example.com', 'auth.example.com'],
+)
+```
+
+### Disable Vision for Sensitive Pages
+
+Prevent screenshots from being sent to the LLM:
+
+```python
+agent = Agent(
+ task='Login and check balance',
+ use_vision=False, # No screenshots sent to LLM
+ sensitive_data={'password': 'secret123'},
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+)
+```
+
+### Domain-Specific Credentials
+
+Route credentials to specific domains only:
+
+```python
+sensitive_data = {
+ 'https://*.work.com': {
+ 'work_user': '[email protected]',
+ 'work_pass': 'work_password',
+ },
+ 'https://personal.com': {
+ 'personal_user': '[email protected]',
+ 'personal_pass': 'personal_password',
+ },
+}
+```
+
+---
+
+## Cloud Browser Profiles
+
+For production deployments, consider [Browser Use Cloud](https://cloud.browser-use.com), which provides:
+
+- Persistent browser profiles in the cloud
+- Pre-authenticated sessions
+- No local Chrome installation required
+- Built-in proxy and fingerprint management
+
+```python
+from browser_use import Agent, Browser, ChatOpenAI
+
+browser = Browser(cdp_url='wss://cloud.browser-use.com/...')
+
+agent = Agent(
+ task='Check my orders',
+ browser=browser,
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+)
+await agent.run()
+```
diff --git a/docs/docs.json b/docs/docs.json
index f26a5db8c..4c23912c6 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -186,6 +186,7 @@
"isDefaultOpen": false,
"pages": [
"customize/browser/basics",
+ "customize/browser/authentication",
"customize/browser/real-browser",
"customize/browser/remote",
"customize/browser/all-parameters"
diff --git a/docs/examples/templates/sensitive-data.mdx b/docs/examples/templates/sensitive-data.mdx
index 940fd6e64..0e6a02d1d 100644
--- a/docs/examples/templates/sensitive-data.mdx
+++ b/docs/examples/templates/sensitive-data.mdx
@@ -5,6 +5,9 @@ icon: "shield"
mode: "wide"
---
+<Note>
+For comprehensive authentication guidance including real browser profiles, storage state, and 2FA, see the [Authentication Guide](/customize/browser/authentication).
+</Note>
```python
import os