Credential fill

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.

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.

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.

import { Hyperbrowser } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({ apiKey: process.env.HYPERBROWSER_API_KEY });
const allowedOrigins = ["https://github.com"];

await client.secrets.create({ name: "github-username", value: process.env.GITHUB_USERNAME!, allowedOrigins });
await client.secrets.create({ name: "github-password", value: process.env.GITHUB_PASSWORD!, allowedOrigins });
await client.secrets.create({
  name: "github-otp",
  type: "totp",
  value: process.env.GITHUB_TOTP_SEED!,
  allowedOrigins,
});

await client.vaults.create({
  name: "github-login",
  entries: {
    USERNAME: { name: "github-username" },
    PASSWORD: { name: "github-password" },
    OTP: { name: "github-otp" },
  },
});

import os
from hyperbrowser import Hyperbrowser

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])
allowed_origins = ["https://github.com"]

client.secrets.create({"name": "github-username", "value": os.environ["GITHUB_USERNAME"], "allowed_origins": allowed_origins})
client.secrets.create({"name": "github-password", "value": os.environ["GITHUB_PASSWORD"], "allowed_origins": allowed_origins})
client.secrets.create({
    "name": "github-otp",
    "type": "totp",
    "value": os.environ["GITHUB_TOTP_SEED"],
    "allowed_origins": allowed_origins,
})

client.vaults.create({
    "name": "github-login",
    "entries": {
        "USERNAME": {"name": "github-username"},
        "PASSWORD": {"name": "github-password"},
        "OTP": {"name": "github-otp"},
    },
})

hx secrets create github-username --allowed-origin https://github.com --from-file ./username.txt
hx secrets create github-password --allowed-origin https://github.com --from-file ./password.txt
hx secrets create github-otp --type totp --allowed-origin https://github.com --from-file ./otp-seed.txt

hx vaults create github-login \
  --entry USERNAME=github-username --entry PASSWORD=github-password --entry OTP=github-otp

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 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. 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).

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";

const client = new Hyperbrowser({ apiKey: process.env.HYPERBROWSER_API_KEY });

const session = await client.sessions.create({ credentials: [{ vault: "github-login" }] });
try {
  const browser = await chromium.connectOverCDP(session.wsEndpoint);
  const page = browser.contexts()[0].pages()[0];
  await page.goto("https://github.com/login");

  const result = await client.sessions.credentials.fill(session.id, {
    vault: "github-login",
    fields: [
      { field: "USERNAME", selector: "#login_field" },
      { field: "PASSWORD", selector: "#password" },
    ],
  });
  console.log(result.origin, result.fields);

  // Fill only types. Submitting is up to you.
  if (result.fields.every((field) => field.outcome === "filled")) {
    await page.click("input[type=submit]");
  }
} finally {
  await client.sessions.stop(session.id);
}

import os
from hyperbrowser import Hyperbrowser
from playwright.sync_api import sync_playwright

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

session = client.sessions.create({"credentials": [{"vault": "github-login"}]})
try:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(session.ws_endpoint)
        page = browser.contexts[0].pages[0]
        page.goto("https://github.com/login")

        result = client.sessions.credentials.fill(session.id, {
            "vault": "github-login",
            "fields": [
                {"field": "USERNAME", "selector": "#login_field"},
                {"field": "PASSWORD", "selector": "#password"},
            ],
        })
        print(result.origin, result.fields)

        # Fill only types. Submitting is up to you.
        if all(field.outcome == "filled" for field in result.fields):
            page.click("input[type=submit]")
finally:
    client.sessions.stop(session.id)

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": [{"vault": "github-login"}]}'

# After navigating the session to https://github.com/login:
curl -X POST https://api.hyperbrowser.ai/api/session/SESSION_ID/credentials/fill \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vault": "github-login",
    "fields": [
      {"field": "USERNAME", "selector": "#login_field"},
      {"field": "PASSWORD", "selector": "#password"}
    ]
  }'

hx browser create --vault github-login
hx browser fill <session-id> --vault github-login \
  --field USERNAME=#login_field --field PASSWORD=#password

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:

await client.sessions.credentials.fill(session.id, {
  credential: "github-password",
  fields: [{ selector: "#password" }],
});

client.sessions.credentials.fill(session.id, {
    "credential": "github-password",
    "fields": [{"selector": "#password"}],
})

curl -X POST https://api.hyperbrowser.ai/api/session/SESSION_ID/credentials/fill \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credential": "github-password", "fields": [{"selector": "#password"}]}'

hx browser fill <session-id> --credential github-password --selector '#password'

The session’s credentials list takes up to 20 items: a secret’s name, { secret: name }, or { vault: name }. 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. 1Password vaults can’t be attached to browser sessions.

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:

await page.waitForSelector("#app_totp");
const otp = await client.sessions.credentials.fill(session.id, {
  vault: "github-login",
  fields: [{ field: "OTP", selector: "#app_totp" }],
});
console.log(otp.fields[0].expiresAt);

page.wait_for_selector("#app_totp")
otp = client.sessions.credentials.fill(session.id, {
    "vault": "github-login",
    "fields": [{"field": "OTP", "selector": "#app_totp"}],
})
print(otp.fields[0].expires_at)

The field’s expiresAt says when the typed code stops being current. If you’re about to submit after that, fill it again.

Results

The response reports an outcome per field, in request order, and never contains values:

{
  "pageId": "6C1F0E5A9B2D47E8A1F3C2B4D5E6F708",
  "origin": "https://github.com",
  "fields": [
    { "field": "USERNAME", "selector": "#login_field", "outcome": "filled", "secretId": "…", "version": 1 },
    { "field": "PASSWORD", "selector": "#password", "outcome": "filled", "secretId": "…", "version": 3 }
  ]
}

Outcome	Meaning
`filled`	The input holds exactly the stored value.
`not_found`	No input matched the selector.
`ambiguous`	More than one visible input matched the selector.
`not_editable`	The input is disabled, read-only, hidden, or not a text input.
`not_accepted`	The page didn’t keep the value, for example because of a `maxlength`.

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. 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 picks a tab in steps. It keeps the tabs whose URL starts with pageUrl, if you pass one. If a single tab is left, it’s used, even if it isn’t on an allowed origin, in which case the fill fails with CREDENTIAL_ORIGIN_NOT_ALLOWED. Otherwise it prefers the tabs on an allowed origin of every secret being filled, when there are any, and then the one visible tab among them. When several tabs could still be the target, the fill fails with CREDENTIAL_PAGE_AMBIGUOUS, and the error’s details list each candidate’s pageId, url and title. Pass pageId (page_id in Python), the tab’s CDP target ID, or a longer pageUrl (page_url) to choose one. 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:

const cdp = await page.context().newCDPSession(page);
const { targetInfo } = await cdp.send("Target.getTargetInfo");

await client.sessions.credentials.fill(session.id, {
  vault: "github-login",
  pageId: targetInfo.targetId,
  fields: [{ field: "PASSWORD", selector: "#password" }],
});

client.sessions.credentials.fill(session.id, {
    "vault": "github-login",
    "page_url": "https://github.com/login",
    "fields": [{"field": "PASSWORD", "selector": "#password"}],
})

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. Give the model your other browser tools as well, since it has to submit the form itself.

import json
from openai import OpenAI
from hyperbrowser.tools import CredentialFillTool

openai_client = OpenAI()
tools = [CredentialFillTool.openai_tool_definition]  # plus your browser tools
messages = [{"role": "user", "content": "Sign in to GitHub with the vault named github-login."}]

while True:
    response = openai_client.chat.completions.create(model="gpt-5", messages=messages, tools=tools)
    message = response.choices[0].message
    messages.append(message)
    if not message.tool_calls:
        break
    for call in message.tool_calls:
        if call.function.name == "fill_credential":
            output = CredentialFillTool.runnable(client, session.id, json.loads(call.function.arguments))
        else:
            output = run_browser_tool(call)  # your click and navigate tools
        messages.append({"role": "tool", "tool_call_id": call.id, "content": output})

import { GoogleGenAI } from "@google/genai";
import { CredentialFillTool } from "@hyperbrowser/sdk/tools";

const ai = new GoogleGenAI({});
const config = { tools: [{ functionDeclarations: [CredentialFillTool.geminiToolDefinition] }] };
const contents: any[] = [{ role: "user", parts: [{ text: "Sign in to GitHub with the vault named github-login." }] }];

while (true) {
  const response = await ai.models.generateContent({ model: "gemini-3.5-flash", contents, config });
  contents.push(response.candidates![0].content);
  if (!response.functionCalls?.length) break;
  const parts = [];
  for (const call of response.functionCalls) {
    const output = await CredentialFillTool.runnable(client, session.id, call.args as any);
    parts.push({ functionResponse: { id: call.id, name: call.name, response: { result: JSON.parse(output) } } });
  }
  contents.push({ role: "user", parts });
}

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.

// Replace the allowed origins, or clear them with null.
await client.secrets.setAllowedOrigins("github-password", ["https://github.com", "https://gist.github.com"]);

// Store a new value; fills use the latest version.
await client.secrets.addVersion("github-password", newPassword);

# Replace the allowed origins, or clear them with None.
client.secrets.set_allowed_origins("github-password", ["https://github.com", "https://gist.github.com"])

# Store a new value; fills use the latest version.
client.secrets.add_version("github-password", new_password)

curl -X PATCH https://api.hyperbrowser.ai/api/secrets/SECRET_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"browser": {"allowedOrigins": ["https://github.com", "https://gist.github.com"]}}}'

hx secrets update github-password --allowed-origin https://github.com --allowed-origin https://gist.github.com
hx secrets set github-password --from-file ./password.txt

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. 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. 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 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 refusal’s metadata.reason is the error code.

cURL

curl "https://api.hyperbrowser.ai/api/session/SESSION_ID/event-logs?types=credential_filled&types=credential_fill_refused" \
  -H "x-api-key: YOUR_API_KEY"

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.

Code	Status	Meaning
`CREDENTIAL_ORIGIN_NOT_ALLOWED`	403	The page’s origin isn’t allowed; `details.origin` names it. Nothing was typed.
`CREDENTIAL_NOT_ATTACHED`	403	The secret wasn’t attached when the session was created, or a vault entry now points at a different secret.
`CREDENTIAL_NOT_READY`	409	The secret has no allowed origins, or no value.
`CREDENTIAL_PAGE_AMBIGUOUS`	409	Several tabs could be the target; pick one from `details.pages`.
`CREDENTIAL_FRAME_AMBIGUOUS`	409	Several frames match the frame URL; make it longer.
`CREDENTIAL_PAGE_NOT_FOUND`, `CREDENTIAL_FRAME_NOT_FOUND`	404	No such tab, or no frame with that URL.
`SECRET_NOT_FOUND`, `VAULT_NOT_FOUND`, `VAULT_ENTRY_NOT_FOUND`	404	No secret, vault or vault entry with that name.
`SECRET_TYPE_MISMATCH`	409	The secret can’t be filled, such as a 1Password token (`op_token`).
`VAULT_SOURCE_INVALID`	400	1Password vaults can’t be used in browser sessions.
`SECRET_SOURCES_INVALID`	400	The vault attached at session create has no entries.
`SECRET_VALUE_INVALID`	422	The stored value can’t be used, such as an invalid TOTP seed. Add a new version.
`SESSION_NOT_ACTIVE`	409	The session has stopped.
`CREDENTIAL_FILL_TIMEOUT`	503, 504	The fill didn’t complete in time. Retryable.
`CREDENTIAL_FILL_FAILED`	500, 502	The browser couldn’t complete the fill.
`CREDENTIALS_UNSUPPORTED_RUNTIME`, `CREDENTIAL_FILL_UNSUPPORTED`, `CREDENTIAL_VALUE_UNSUPPORTED`	400, 501	The session’s browser can’t fill credentials, or can’t produce this value type.
`CREDENTIALS_SNAPSHOT_PASSWORD_MANAGER_ENABLED`	400	The session restores a snapshot taken with Chrome’s password manager on.
`SECRETS_FEATURE_DISABLED`	403	Secrets aren’t enabled for your team yet. Please contact support to enable them.

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.

Get Started

Browser Sessions

Session Configuration

Web API

Agents

HyperAgent Usage

Scraping

Integrations

One-time codes

Results

Choose the page and frame

Use with an LLM

Manage logins

How credentials are protected

Errors

​Store a login

​Fill a login form

​One-time codes

​Results

​Choose the page and frame

​Use with an LLM

​Manage logins

​How credentials are protected

​Errors

Store a login

Fill a login form

One-time codes

Results

Choose the page and frame

Use with an LLM

Manage logins

How credentials are protected

Errors