Secrets

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.

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)

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

const password = process.env.PORTAL_PASSWORD;
if (!password) throw new Error("Set PORTAL_PASSWORD before starting a run");

const client = new BrowserUse();
const run = await client.runs.create({
  task: "Open https://portal.example.com/login, enter portal_password in the password field, and stop before submitting",
  secretBindings: [
    {
      alias: "portal_password",
      source: { type: "inline", value: password },
      allowedDomains: ["portal.example.com"],
    },
  ],
});
console.log(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.

Checkout and payment frames

allowedDomains is checked against the focused field’s frame, not just the shop page. For checkout automation, add the hostnames of payment or billing providers whose embedded fields should receive the secret. A shop’s hostname does not authorize unrelated third-party frames. For example, if a shop embeds BigCommerce fields from https://payments.bigcommerce.com, the relevant binding could use:

{ "allowedDomains": ["shop.example.com", "payments.bigcommerce.com"] }

Replace the example shop and provider with the actual field hostnames. Only add a provider you intend to receive that secret; do not broaden the binding to every frame or the provider’s parent domain. No shared provider list or model change is required.

Error	What to do
`domain_not_allowed`	Read the returned `origin`; if it is an intended HTTPS payment or billing provider, add its hostname to that secret binding’s `allowedDomains` and pass the updated binding in a follow-up run.
`target_not_editable`	Focus an enabled editable input in the correct frame and wait for it to be ready; changing `allowedDomains` does not fix this error.

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.

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"],
)

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

const client = new BrowserUse();
const result = await client.run(
  "Log into GitHub and star the browser-use/browser-use repo",
  {
    secrets: { "github.com": "username:password123" },
    allowedDomains: ["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:

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

const result = await client.run(
  "Log into the company portal and download the Q4 report",
  {
    secrets: {
      "portal.example.com": "user@company.com:password123",
      "okta.com": "user@company.com:password123",
    },
    allowedDomains: ["portal.example.com", "*.okta.com"],
  },
);

Get Started

Pillars

More

API V4: inline secret bindings

Checkout and payment frames

Legacy API V2

​API V4: inline secret bindings

​Checkout and payment frames

​Legacy API V2

API V4: inline secret bindings

Checkout and payment frames

Legacy API V2