Secrets

Pass run-scoped credentials to API V4 with secret bindings.

API V4: inline secret bindings

Use secret_bindings / secretBindings with the explicit V4 client. Give each credential an alias and the hostnames where it may be typed. Refer to the alias in the task, not the credential value.

Aliases avoid putting raw credentials in the task text. They do not guarantee that the agent cannot see the value: once typed, it is accessible to the page and to an agent with browser/CDP access.

This example fills a password field and stops before submitting. Replace the example portal URL and provide PORTAL_PASSWORD through your application’s secret store or environment. Do not commit the value or print the request body.

Python

import os
from browser_use_sdk.v4 import BrowserUse

with BrowserUse() as client:
    run = client.runs.create(
        "Open https://portal.example.com/login, enter portal_password "
        "in the password field, and stop before submitting",
        secret_bindings=[
            {
                "alias": "portal_password",
                "source": {
                    "type": "inline",
                    "value": os.environ["PORTAL_PASSWORD"],
                },
                "allowedDomains": ["portal.example.com"],
            }
        ],
    )
    print(run.id)

• allowedDomains takes bare hostnames, not URLs, ports, paths, or wildcards. A hostname also covers its subdomains. Use the narrowest host that works.
• These domains restrict where that credential may be typed. They are not a browser-wide navigation or network allowlist.
• Bindings belong to one run. A follow-up that needs the same credential must pass the binding again, even when it reuses the same session.
• Use a separate alias for each credential field. Up to 20 bindings are allowed per run, with up to 20 allowed domains per binding.
• Aliases contain 1–64 lowercase letters, digits, hyphens, or underscores and start with a letter or digit.
• The inline limit is 4,096 bytes after JSON encoding for encryption, including its wrapper and escaping. It is not a 4,096-character allowance; non-ASCII characters, quotes, and backslashes consume extra space.

For credentials stored in a connected vault, use a 1Password field binding. See the Create run reference for the current request schema.

Legacy API V2

The examples below use the default V2 client and its secrets / allowed_domains fields. Do not pass those fields to v4.runs.create(); use the secret bindings above. Keep this recipe only for an existing V2 integration.

Pass credentials to the agent scoped by domain.

Python

from browser_use_sdk import AsyncBrowserUse

client = AsyncBrowserUse()
result = await client.run(
    "Log into GitHub and star the browser-use/browser-use repo",
    secrets={"github.com": "username:password123"},
    allowed_domains=["github.com"],
)

Use allowed_domains to restrict the agent to specific domains. Supports wildcards: example.com, *.example.com.

For SSO/OAuth redirects, include all domains in the auth flow:

Python

result = await client.run(
    "Log into the company portal and download the Q4 report",
    secrets={
        "portal.example.com": "[e-mail]:password123",
        "okta.com": "[e-mail]:password123",
    },
    allowed_domains=["portal.example.com", "*.okta.com"],
)