1Password & 2FA

​

Service account

​

Setup

​

1. Create a dedicated vault

​

2. Create a service account token

1. In 1Password, open Developer > Service Accounts (guide)
2. Click New Service Account, name it “Browser Use Cloud”
3. Grant read access to the dedicated vault
4. Copy the generated token

​

3. Connect to Browser Use Cloud

1. Go to Browser Use Cloud Settings - Secrets
2. Click Connect 1Password
3. Paste your service account token

​

Use a vault in a v4 run

curl -X POST https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Open amazon.com, log in, and check my recent orders",
    "opVaultId": "<vault-id>"
  }'

• Where credentials may be typed. By default each item’s credentials can only be typed on the hosts of the websites saved on that item in 1Password, so the Amazon password works on amazon.com and its subdomains, but not on other items’ sites. Websites marked “Never autofill” are ignored.
• Items with no usable website (none saved, only invalid URLs, or only “Never autofill” entries) are skipped, and their titles come back in skippedVaultItems on the run response. The run starts as long as at least one vault credential is left; if every credential is skipped, the API returns 422.
• Override with opVaultAllowedDomains. Pass a list such as ["amazon.com"] to use the same hosts for every item in the vault instead. Use bare hostnames.
• Subdomains. Either way, a hostname also covers its subdomains, so amazon.com allows login.amazon.com. 1Password’s exact-domain autofill setting is not honored.
• Aliases. Vault items become aliases based on their titles, with _username, _password, or _bu_2fa_code suffixes. Security answers get a suffix named after the question, for example chase_where_married.
• Limit. Vault fields and explicit secretBindings share a limit of 20 bindings per run, and each filled security answer counts as one. The API returns 422 if the combined total exceeds 20.
• Vault access requires exactly one active 1Password integration on the project and is unavailable for zero-data-retention projects.

​

Bind individual fields in a v4 run

from browser_use_sdk.v4 import BrowserUse

with BrowserUse() as client:
    run = client.runs.create(
        "Log into Jira and create a ticket for the Q4 release",
        secret_bindings=[
            {
                "alias": "jira_password",
                "source": {
                    "type": "onepassword",
                    "integrationId": "<integration id from Settings → Secrets>",
                    "vaultId": "<vault id>",
                    "itemId": "<item id>",
                    "fieldId": "password",
                },
                "allowedDomains": ["atlassian.net"],
            }
        ],
    )
    print(client.runs.wait_for_completion(run.id).result)

import { BrowserUse } from "browser-use-sdk/v4";

const client = new BrowserUse();
const run = await client.runs.create({
  task: "Log into Jira and create a ticket for the Q4 release",
  secretBindings: [
    {
      alias: "jira_password",
      source: {
        type: "onepassword",
        integrationId: "<integration id from Settings → Secrets>",
        vaultId: "<vault id>",
        itemId: "<item id>",
        fieldId: "password",
      },
      allowedDomains: ["atlassian.net"],
    },
  ],
});

• integrationId is the 1Password integration you connected under Settings → Secrets.
• vaultId and itemId are the 1Password UUIDs of the vault and item (copy them from 1Password).
• fieldId is the field’s id, not its label: username, password, or one-time-password for a TOTP field, which resolves to the current code.
• allowedDomains are bare hostnames; a host covers its subdomains.

​

Use a vault in a v2 task

from browser_use_sdk import AsyncBrowserUse

client = AsyncBrowserUse()
result = await client.run(
    "Log into my Jira account and create a new ticket",
    op_vault_id="your-vault-id",
    allowed_domains=["*.atlassian.net"],
)
print(result.output)

import { BrowserUse } from "browser-use-sdk";

const client = new BrowserUse();
const result = await client.run(
  "Log into my Jira account and create a new ticket",
  {
    opVaultId: "your-vault-id",
    allowedDomains: ["*.atlassian.net"],
  },
);
console.log(result.output);

result = await client.run(
    "Log into Jira and create a ticket for the Q4 release",
    op_vault_id="your-vault-id",
    allowed_domains=["*.atlassian.net", "*.okta.com"],
)

const result = await client.run(
  "Log into Jira and create a ticket for the Q4 release",
  {
    opVaultId: "your-vault-id",
    allowedDomains: ["*.atlassian.net", "*.okta.com"],
  },
);

​

Personal 1Password

​

Connect your account

1. Go to Settings - Secrets and find Agentic Autofill: Personal.
2. Click Connect personal 1Password and sign in with your personal 1Password account.
3. On the consent screen (“Browser Use wants to connect to your 1Password account”), click Connect.
4. You are sent back to Browser Use, which shows Ready for your first login.

​

Use it in a run

1. In the run composer, turn on 1Password (“Use your 1Password for this run”). It is off by default and has to be turned on for each run.
2. When the agent reaches a login page, it requests a login from 1Password and the run shows Waiting for your approval.
3. Click Open 1Password on that card and allow your browser to open the 1Password desktop app if it asks. The app must be signed in to the same personal account.
4. Review the request in 1Password and approve it. 1Password fills the login.

​

Personal 1Password with your own agent (CDP)

​

Before you start

1. Get OAuth apps enabled by 1Password. OAuth apps for Agentic Autofill are not enabled by default: until 1Password enables them for your 1Password Business account (not Teams), there is no option to create one. Ask your 1Password contact, or contact us and we will introduce you.
2. Register your OAuth app. As an owner or administrator of that Business account, go to Integrations > OAuth Application. Enter the name and icon your users will see (the icon cannot be added later), your https redirect URL, grant type Authorization code and scope Read credentials. Store the client ID and secret; the secret is shown once.
3. Upload the 1Password extension once with POST /api/v4/extensions (see Extensions): a ZIP, with manifest.json at its root, of the 1Password Nightly extension, version 8.12.46.6 or newer (see 1Password’s supported builds). Keep the returned id. In Browser Use browsers the extension gets its own runtimeId, so do not use the Chrome Web Store extension id.

​

Connect each user once

1. Generate an unpredictable state and a PKCE code_verifier, and store both with the signed-in user’s pending connection. Send the user to https://my.1password.com/oauth/authorize (no /v1) with response_type=code, client_id, redirect_uri (exactly as registered), scope=brokered-credentials:request-access brokered-credentials:read, state, code_challenge and code_challenge_method=S256.
2. Your redirect URL carries code and state in the query. Reject a missing, mismatched or already used state before you accept anything (see 1Password’s callback contract). On first consent it also carries an integration_key in the fragment (#integration_key=...). Browsers do not send fragments to your server, so read it in the browser, send it to your backend, store it before you exchange the code, then clear it from the address bar. It is delivered only once per connection; never overwrite a stored key with an empty value, and only reuse a stored key for the same user and 1Password account.
3. Exchange the code: POST https://api.1password.com/v1/oauth/token, form-encoded grant_type=authorization_code, code, code_verifier, redirect_uri, with HTTP Basic auth (client ID and secret, not in the body). The response has access_token, refresh_token and expires_in.
4. Access tokens last about 15 minutes. Refresh with the same endpoint and auth, form-encoded grant_type=refresh_token and refresh_token. Refresh tokens rotate, so store the new one every time (serialize refreshes per user). The refresh response never contains the integration_key, so keep the stored one.

​

Sign a user in

1. Create a browser with the extension: POST /api/v4/browsers with "extensionIds": ["<extension id>"]. Read extensions[0].runtimeId from the response.
2. cdpUrl is an https:// URL. Playwright’s connectOverCDP accepts it directly; for raw CDP, take webSocketDebuggerUrl from {cdpUrl}/json/version.
3. Find the target with type: "service_worker" and url chrome-extension://<runtimeId>/background/background.js (Target.getTargets, retry for a few seconds), and attach with Target.attachToTarget and flatten: true. Stay attached until you are done: the worker can suspend after about 30 seconds without a connection.
4. Call the extension’s API with Runtime.callFunctionOn (awaitPromise: true, returnByValue: true), passing tokens as CDP arguments. Every call returns {success, result} or {success: false, error}; check success first.
5. api.initialization.v1.whenSettled() (resolves to "ready"), then api.agenticMode.v1.enable().
6. api.agenticAutofill.v1.createAccessRequest. Show the returned appLink (onepassword://...) as an Open 1Password button in your app, to open on the computer where the user’s 1Password app is signed in. The prompt closes after 2 minutes.
7. Start polling getAccessRequestStatus when the user opens the link (1Password’s schedule): wait 5 seconds, then every 2 seconds, every 5 seconds after 30 seconds, every 10 seconds after a minute, every 20 seconds after 2 minutes, and stop after 3 minutes. If it is still pending, offer an “I approved it” button that checks once more, or create a new request. On rateLimitExceeded, wait at least a minute. Stop on denied, expired or any state you do not know. When it is resolved, take the reference of the grant whose entryId equals the id of the entry you requested (users can skip or add logins, so do not rely on array position).
8. Open the login page with chrome.tabs.create in the worker, wait until chrome.tabs.get(id).status is complete (abort if it never is), check that the tab’s scheme, host and port still match the approved website exactly, then call fillCredential with that reference as resourcePath and the Chrome tab id as tabId.
9. {"status": "fill_submitted"} means the form was submitted, not that the sign-in worked. Check the page: the site can reject the credentials or ask for another step. Then hand the browser to your agent.
10. Stop the browser when the task is done (PATCH /api/v4/browsers/{id} with {"action": "stop"}); closing CDP alone does not stop it.

# pip install websockets
import asyncio, json, os, sys, time, urllib.parse, urllib.request, webbrowser
import websockets

API = "https://api.browser-use.com/api/v4"
BU_KEY = os.environ["BROWSER_USE_API_KEY"]
EXTENSION_ID = os.environ["OP_EXTENSION_ID"]  # id from POST /api/v4/extensions
ACCESS_TOKEN = os.environ["OP_ACCESS_TOKEN"]  # fresh token for this end user
INTEGRATION_KEY = os.environ["OP_INTEGRATION_KEY"]
LOGIN_URL = "https://example.com/login"
WEBSITE = "https://example.com"


def same_site(url, website):
    """True only for the exact scheme, host and port of the approved website."""
    a, b = urllib.parse.urlsplit(url), urllib.parse.urlsplit(website)
    port = lambda u: u.port if u.port is not None else {"https": 443, "http": 80}.get(u.scheme)
    return (not a.username and not a.password and a.scheme == b.scheme
            and a.hostname == b.hostname and port(a) == port(b))


def api(method, path, body=None):
    req = urllib.request.Request(API + path, method=method,
                                 data=json.dumps(body).encode() if body else None,
                                 headers={"X-Browser-Use-API-Key": BU_KEY, "Content-Type": "application/json"})
    return json.load(urllib.request.urlopen(req))


async def main():
    browser = api("POST", "/browsers", {"extensionIds": [EXTENSION_ID]})
    try:
        runtime_id = browser["extensions"][0]["runtimeId"]  # not 1Password's Chrome Web Store id
        # cdpUrl is https://; raw CDP needs the WebSocket URL from /json/version
        ws_url = json.load(urllib.request.urlopen(browser["cdpUrl"].rstrip("/") + "/json/version"))["webSocketDebuggerUrl"]
        async with websockets.connect(ws_url, max_size=None) as ws:
            n = 0

            async def send(method, params=None, session=None):
                nonlocal n
                n += 1
                await ws.send(json.dumps({"id": n, "method": method, "params": params or {},
                                          **({"sessionId": session} if session else {})}))
                while True:
                    msg = json.loads(await ws.recv())
                    if msg.get("id") == n:
                        if "error" in msg:
                            raise RuntimeError(msg["error"])
                        return msg["result"]

            # Find and attach to the 1Password service worker. Stay attached while you poll.
            worker_url = f"chrome-extension://{runtime_id}/background/background.js"
            for _ in range(30):
                targets = (await send("Target.getTargets"))["targetInfos"]
                worker = next((t for t in targets if t["type"] == "service_worker" and t["url"] == worker_url), None)
                if worker:
                    break
                await asyncio.sleep(1)
            else:
                sys.exit("1Password service worker not found")
            session = (await send("Target.attachToTarget", {"targetId": worker["targetId"], "flatten": True}))["sessionId"]
            this = (await send("Runtime.evaluate", {"expression": "globalThis"}, session))["result"]["objectId"]

            async def call(fn, *args):
                # Pass tokens as CDP arguments, never inside the script string.
                r = await send("Runtime.callFunctionOn", {
                    "objectId": this, "functionDeclaration": fn, "arguments": [{"value": a} for a in args],
                    "awaitPromise": True, "returnByValue": True}, session)
                if "exceptionDetails" in r:
                    raise RuntimeError(r["exceptionDetails"])
                return r["result"].get("value")

            def ok(response):  # every 1Password call returns {success, result} or {success: false, error}
                if not response or not response.get("success"):
                    sys.exit(f"1Password error: {response and response.get('error')}")
                return response.get("result")

            await call("function() { return this.api.initialization.v1.whenSettled(); }")
            ok(await call("function() { return this.api.agenticMode.v1.enable(); }"))

            created = ok(await call(
                "function(accessToken, integrationKey, website) {"
                "  return this.api.agenticAutofill.v1.createAccessRequest({accessToken, integrationKey, requests: {"
                "    version: 2, goal: 'Sign in to ' + website,"
                "    entries: [{type: 'login', parameters: {website}, reason: 'Your assistant needs to sign in'}]}});"
                "}", ACCESS_TOKEN, INTEGRATION_KEY, WEBSITE))
            request_id = created["accessRequest"]["id"]
            entry_id = created["accessRequest"]["entries"][0]["id"]
            # In your app: show an "Open 1Password" button for created["appLink"] (never log it) and
            # start polling when the user clicks it. This demo opens it on the machine it runs on.
            if not webbrowser.open(created["appLink"]):
                sys.exit("could not open the 1Password link")

            # 1Password's schedule, counted from the moment the user opened the link.
            started, reference = time.time(), None
            await asyncio.sleep(5)
            while time.time() - started < 180:
                status = await call(
                    "function(accessToken, integrationKey, accessRequestUUID) {"
                    "  return this.api.agenticAutofill.v1.getAccessRequestStatus({accessToken, integrationKey, accessRequestUUID});"
                    "}", ACCESS_TOKEN, INTEGRATION_KEY, request_id)
                if not status.get("success") and (status.get("error") or {}).get("code") == "rateLimitExceeded":
                    await asyncio.sleep(60)
                    continue
                state = ok(status)["state"]
                if state == "resolved":
                    grant = next((g for g in status["result"]["resolved"] if g.get("entryId") == entry_id), None)
                    reference = grant and grant["reference"]
                    break
                if state != "pending":  # denied, expired, or anything unknown: stop
                    sys.exit(f"access request {state}")
                elapsed = time.time() - started
                await asyncio.sleep(2 if elapsed < 30 else 5 if elapsed < 60 else 10 if elapsed < 120 else 20)
            if not reference:
                # Offer an "I approved it" button that checks once more, or create a new request.
                sys.exit("not approved in time")

            # Open the login page as a Chrome tab, wait for it, check the origin, then fill.
            tab_id = (await call("function(url) { return chrome.tabs.create({url, active: true}); }", LOGIN_URL))["id"]
            for _ in range(60):
                tab = await call("function(id) { return chrome.tabs.get(id); }", tab_id)
                if tab["status"] == "complete":
                    break
                await asyncio.sleep(0.5)
            else:
                sys.exit("login page did not finish loading")
            if not same_site(tab["url"], WEBSITE):
                sys.exit("tab left the approved website")
            # Your agent must not read this tab until fillCredential returns.
            result = ok(await call(
                "function(accessToken, integrationKey, resourcePath, tabId) {"
                "  return this.api.agenticAutofill.v1.fillCredential({accessToken, integrationKey, resourcePath, tabId});"
                "}", ACCESS_TOKEN, INTEGRATION_KEY, reference, tab_id))
            print("fill:", result["status"])  # fill_submitted = form submitted, not proof of sign-in
            await asyncio.sleep(3)
            print("page after fill:", (await call("function(id) { return chrome.tabs.get(id); }", tab_id))["url"])
    finally:
        api("PATCH", f"/browsers/{browser['id']}", {"action": "stop"})


asyncio.run(main())

​

Rules

• Keep the model off the page while a fill runs. The values are in the page until fillCredential returns. Until then, pause your agent and block DOM reads, screenshots and other CDP commands to that tab, for example with a lock in your orchestrator. Do not install untrusted extensions in the same browser. See 1Password’s fill guidance.
• Keep the extension session, tokens and the appLink out of the agent’s and model’s context and out of your logs. Do not log CDP traffic: it carries the token and key.
• Do not turn on session recording for browsers that run fills.

​

Security questions

• Title each field with the question as the site words it. The agent matches the page’s question to the key.
• Only Login items are read, and only fields with a value. Empty fields are skipped.
• In v4, a question written only in a non-Latin script gets the alias <item>_answer, which does not say which question it answers. If an item has several such questions, write their titles in English.
• The same allowedDomains rules apply as for the item’s password.

​

How it works

1. It identifies the service (e.g., Twitter, GitHub, LinkedIn)
2. Retrieves matching credentials from your 1Password vault
3. Fills in the username and password
4. If 2FA is required and a TOTP code is stored, it generates and enters the code automatically
5. If the site asks a security question, it enters the matching stored answer