Skip to main content
Credential fill types stored secrets, such as a username, a password or a one-time code, into a login form in a browser session. Values are encrypted on your machine before they’re uploaded, and the API never returns them. When your session reaches a login page, you ask Hyperbrowser to fill the form: the values are decrypted on the host running the session’s browser and typed into the inputs you choose. Your code, your logs and any LLM driving the browser refer to the secrets by name only. If your logins live in 1Password, a session can also fill fields read from 1Password without storing them.
Credential fill is in public preview and is enabled for teams on request. Please contact us at info@hyperbrowser.ai or on our support chat to enable it for your team. A restricted API key needs secrets.manage to create secrets and vaults, secrets.use to attach them to a session, and secrets.use with browser.sessions.update to fill them. It’s available in the Node SDK from 1.3.0, the Python SDK from 1.13.0, and the CLI.

Store a login

A login is a few ordinary secrets, one per input, each with the allowed origins it may be typed into. A secret can’t be filled until it has at least one. To fill a one-time code, store the authenticator seed as a secret of type totp: each fill types the code that’s current at that moment. Group the secrets in a vault so you can attach and fill them by one name. The vault’s entry names, such as USERNAME and PASSWORD, are the field names you fill by.
An allowed origin is scheme://host[:port], with no path. https://*.example.com matches any subdomain of example.com but not example.com itself, and http:// is accepted only for localhost, 127.0.0.1 and [::1]. A secret takes 1–20 origins. Allowed origins only limit fills: the same secret can still be passed to a sandbox, where a process that names it, or a vault holding it, receives the value, or a totp secret’s current code. A TOTP value is the authenticator’s base32 seed, or an otpauth://totp/... URI when the site uses a non-default algorithm, digit count or period. Spaces, hyphens, line breaks and lowercase letters in a seed are fine. The SDKs and CLI check the value before uploading it, because the API can’t see it: an invalid seed only fails when it’s used. To change a secret’s origins later, see Manage logins.

Fill a login form

Attach the vault, or single secrets, when you create the session; a session can only fill what it was created with. Then navigate to the login page and fill it. These examples use Playwright: install playwright-core (Node.js) or playwright (Python).
Each field names a vault entry and the CSS selector of its input. To fill one secret instead, pass credential with the secret’s name or ID and give each field only a selector:
The session’s credentials list takes up to 20 items: a secret’s name, { secret: name }, { vault: name }, or { onePassword: name } for a 1Password token. A vault attaches the secrets its entries point at when the session is created. Attaching anything forces a Firecracker browser and turns off Chrome’s password manager. Each fill passes exactly one of credential, vault or onePassword.

One-time codes

Logins with two-step verification usually ask for the code on the next screen. Submit the first screen, then fill the totp entry there:
The field’s expiresAt says when the typed code stops being current. If you’re about to submit after that, fill it again.

Fill from 1Password

A session can type fields read from your 1Password account, so you don’t have to store the login in Hyperbrowser. Store a service account token as an op_token secret, and attach it when you create the session with { onePassword: "op-token" } in credentials. Attaching the token lets fills read with it; the token itself is never typed. Naming an op_token as a plain credential, "op-token" or { secret: "op-token" }, fails with SECRET_TYPE_MISMATCH. To fill, pass onePassword with the token’s name, the 1Password vault’s name or ID, and the allowedOrigins the values may be typed on. Each field gives the input’s selector and, in ref, the item, an optional section and the field to type:
In the CLI, --1password-ref takes item/[section/]field, and the nth --1password-ref fills the nth --selector. allowedOrigins is required: 1–20 origins with the same rules as a secret’s allowed origins. An origin that breaks them fails the fill with SECRET_METADATA_INVALID. A stored secret carries its own origins, but nothing stored in Hyperbrowser says where a 1Password value belongs, so the request does. The browser checks the target page against them exactly as it does for stored secrets, and tab choice uses them in the same way. Each ref follows the 1Password reference rules and reads op://<vault>/<item>/[<section>/]<field>. To type a one-time code, add ?attribute=otp to its field, such as { item: "scrapingcourse login", field: "one-time password?attribute=otp" }. A fill uses one token and one 1Password vault, every field needs a ref, and ref can’t be used with credential or vault. Each fill reads the fields from 1Password at that moment, with the token’s latest version. The result has each field’s reference, and the secretId and version of the token it was read with. It has no field or expiresAt, and no top-level version:
The event log records the token’s name as onePasswordToken, with its secretId, where other fills record credential or vault. The LLM tool doesn’t fill from 1Password, so call fill from your code. Besides the errors of any fill, you can get: The SECRET_ONEPASSWORD_* errors name the token version they used in details.tokenSecretId and details.tokenVersion.

Results

The response reports an outcome per field, in request order, and never contains values:
Each field also reports the secretId and version typed, and expiresAt for a TOTP code. A single-secret fill also has a top-level version, and a 1Password fill reports each field’s reference. Only inputs a person could see count toward a selector, so a hidden copy of a form, such as a mobile layout or a honeypot field, is skipped. A fill takes 1–16 fields, each selector at most once. It never submits the form and is safe to retry. For logins split over several screens, fill the fields on the current screen, submit, and fill the rest on the next one.

Choose the page and frame

Without a page ID, the fill chooses a tab like this:
  1. If you pass pageUrl, only tabs whose URL starts with it are considered.
  2. If one tab is left, that’s the target.
  3. If several are left, it prefers the tabs on an origin that every secret being filled allows, or that the request’s allowedOrigins allow for 1Password, if any are open, and then the visible tab among them. With frameUrl, tabs aren’t narrowed by origin, since a login iframe’s tab is usually on another origin.
  4. If more than one tab still qualifies, the fill fails with CREDENTIAL_PAGE_AMBIGUOUS, and the error’s details list each candidate’s pageId, url and title.
The origin of the chosen tab, or of the frame inside it, is then checked against the allowed origins. If it isn’t allowed, nothing is typed and the fill fails with CREDENTIAL_ORIGIN_NOT_ALLOWED. To choose the tab yourself, pass pageId (page_id in Python), the tab’s CDP target ID, or a longer pageUrl (page_url). You can’t pass both. Under Playwright every tab reports as visible, so pass a page when more than one open tab is on an allowed origin:
For a login form inside an iframe, pass frameUrl (frame_url in Python; frame: { "url": … } in the API) with the start of the iframe’s URL, such as https://accounts.example.com/login. The iframe’s own origin must be allowed.

Use with an LLM

Both SDKs include a fill_credential tool definition for OpenAI, Anthropic and Gemini, and a runner that executes the model’s call in the session you bind. The model chooses a secret (credential) or a vault, the field and selector for each input, and optionally page_id, page_url or frame_url; it never sees the values. The runner returns JSON text for the model: the fill result, or {"error": {"code", "message", "retryable", "details"}} so the model can react, for example by retrying with a page_id from details.pages. The tool doesn’t offer 1Password. A 1Password fill names its allowed origins in the request, so a model choosing them would choose where your values may be typed. For 1Password, call fill from your code. Give the model your other browser tools as well, since it has to submit the form itself.
The definitions are openai_tool_definition, anthropic_tool_definition and gemini_tool_definition in Python, and openaiToolDefinition, anthropicToolDefinition and geminiToolDefinition in Node.js. Python also has CredentialFillTool.async_runnable for AsyncHyperbrowser.

Manage logins

Login secrets are ordinary secrets, so you manage them with the secrets methods; see Secrets to rotate values and Vaults to change entries. Each method takes a name or ID.
The API addresses secrets by ID; {"metadata": {"browser": null}} clears the origins, after which the secret can’t be filled.

How credentials are protected

  • Encrypted before upload. Values are encrypted on your machine and decrypted only by the host running the session that fills them. 1Password values are read by that host at fill time and never stored. No endpoint returns a value, and fill results contain outcomes only.
  • Typed only on allowed origins. Before anything is typed, the origin the browser reports for the target page or frame is checked against the allowed origins of every secret being filled, or for 1Password against the request’s allowedOrigins, since nothing stored says where a 1Password value belongs. On any other origin the fill fails with CREDENTIAL_ORIGIN_NOT_ALLOWED and nothing is typed. Allowed origins don’t apply to sandboxes, which receive any secret a process names; keep a login’s secrets out of vaults used with sandboxes if only browsers should have them.
  • Attached up front. A session can only fill secrets, or read with 1Password tokens, attached when it was created. Attaching forces a Firecracker browser and turns off Chrome’s password manager.
  • Never submitted for you. Fill only types. Your code or model decides whether to submit.
  • Kept out of replays. Inputs a fill writes to are excluded from session replays.
  • Tracked through snapshots. A session that received a credential, and its snapshots, are marked as containing secrets. Restoring such a snapshot needs the same access as using credentials.
  • Recorded. Every fill and every refused attempt is written to the session’s event log as credential_filled or credential_fill_refused, with the secret IDs and versions, never values. A 1Password fill records the token’s name as onePasswordToken, and each field’s reference. A refusal’s metadata.reason is the error code.
cURL
Some things stay readable. Once a value is in a page, the site’s scripts, browser extensions, and your own CDP connection to the session can read the field. Video recordings and the live view show what’s on screen: password inputs are masked by the page, but a filled username or one-time code is visible.

Errors

Errors have a code, a message, and sometimes retryable and details. A fill can take up to about 18 seconds, so give your HTTP client a timeout of at least 30 seconds. The SDKs do this for you.