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 typetotp: 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.
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: installplaywright-core (Node.js) or playwright (Python).
credential with the secret’s name or ID and give each field only a selector:
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 thetotp entry there:
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 anop_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:
--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:
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:- If you pass
pageUrl, only tabs whose URL starts with it are considered. - If one tab is left, that’s the target.
- If several are left, it prefers the tabs on an origin that every secret being filled allows, or that the request’s
allowedOriginsallow for 1Password, if any are open, and then the visible tab among them. WithframeUrl, tabs aren’t narrowed by origin, since a login iframe’s tab is usually on another origin. - If more than one tab still qualifies, the fill fails with
CREDENTIAL_PAGE_AMBIGUOUS, and the error’s details list each candidate’spageId,urlandtitle.
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:
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 afill_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.
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.{"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 withCREDENTIAL_ORIGIN_NOT_ALLOWEDand 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_filledorcredential_fill_refused, with the secret IDs and versions, never values. A 1Password fill records the token’s name asonePasswordToken, and each field’sreference. A refusal’smetadata.reasonis the error code.
cURL
Errors
Errors have acode, 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.