--- title: "Fill a credential" method: POST path: "/api/session/{id}/credentials/fill" --- # Fill a credential `POST /api/session/{id}/credentials/fill` ## Request - Base URL: `https://api.hyperbrowser.ai` - URL: `https://api.hyperbrowser.ai/api/session/{id}/credentials/fill` - Auth: API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Types a secret, a vault's entries, or fields read from 1Password into inputs on a page in the session. The values are decrypted on the session's host; neither the request nor the response contains them. Fill only types: it never submits, so click the submit button or press Enter afterwards. Nothing is typed unless the target frame is on an allowed origin of every secret being filled, or for `onePassword` on one of the request's `allowedOrigins`. A `totp` secret types the code current at fill time. A fill is safe to retry. Without `pageId`, Hyperbrowser considers the tabs whose URL starts with `pageUrl` (if given). If one is left, it's the target. If several are left, it prefers the tabs on an origin every secret (or `onePassword.allowedOrigins`) allows, unless `frame` is given, then the visible one among them; if more than one still qualifies, it returns 409 CREDENTIAL_PAGE_AMBIGUOUS listing the tabs. The chosen tab's origin is then checked, and a tab outside the allowed origins gets 403 CREDENTIAL_ORIGIN_NOT_ALLOWED with nothing typed. Requires an active Firecracker browser session created with these secrets, or the `onePassword` token, in `credentials`. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need both the browser.sessions.update and secrets.use scopes. A fill can take up to about 18 seconds, so set your client timeout to at least 30 seconds. Fills and refusals are recorded in the session's event logs as `credential_filled` and `credential_fill_refused`, with `credential`, `vault`, or for 1Password the token's name as `onePasswordToken`, and never values. ## Path parameters - `id` string, uuid, required ## Request body - CredentialFillParams: Provide exactly one of `credential`, `vault` and `onePassword` (otherwise 400 "Pass one of credential, vault or onePassword"). With `vault`, every field has `field`; with `onePassword`, every field has `ref`; with `credential`, fields have only a `selector`. - `credential` string: A secret's name or ID (names are matched first). It must have been attached to the session when the session was created, directly or through a vault. Each field then has only a `selector`. - `vault` string: A vault's name. Each field's `field` names the entry whose secret is typed; the entry's secret must have been attached when the session was created. - `onePassword` CredentialFillOnePassword: Fill fields read from 1Password with an `op_token` secret attached to the session as `{"onePassword": name}` in `credentials` (otherwise 403 CREDENTIAL_NOT_ATTACHED). Each field names its 1Password field in `ref`. The session's host reads the fields at fill time; nothing is stored. 1Password errors carry `details.tokenSecretId` and `details.tokenVersion`. - `token` union, required: The `op_token` secret, by name, holding the service account token. A name uses its latest version. An unknown name returns 404 SECRET_NOT_FOUND, a secret of another type 409 SECRET_TYPE_MISMATCH, and a token without a value 404 SECRET_VERSION_NOT_FOUND. A customer-protected token is passed as `{name, version, unwrapped}`, as for `secrets`. - string - SecretReference - `name` string, required: Name of a secret of type `secret` or `totp`. A `totp` variable holds the code current when the process starts. A customer-protected secret also needs `unwrapped` (otherwise 400 SECRET_REQUIRES_CUSTOMER_UNWRAP). - `version` union: A version number, or `latest`. Omit for the latest version. - 'latest' - integer - `unwrapped` string: Customer-protected secrets only, and required for them: the inner envelope you unwrapped from GET /api/secrets/{id}/versions/{version}/wrapped. `version` must then be that version's number, not `latest`. See [Customer-protected secrets](/sandboxes/customer-keys). - `vault` string, required: The 1Password vault's name or ID. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`. - `allowedOrigins` string[], required: Origins the values may be typed on, with the same rules as a secret's `metadata.browser.allowedOrigins`: `scheme://host[:port]` with no path, https except for localhost, 127.0.0.1 and [::1], and `*.` only before a registrable domain. Required: nothing stored says where a 1Password value belongs, so the request does. The browser checks the target frame against them as it does a stored secret's, and tab choice uses them. An invalid origin returns 400 SECRET_METADATA_INVALID. - `fields` CredentialFillField[], required: The inputs to type into. Each selector may appear once. - `field` string: With `vault`, the entry to type, such as `PASSWORD`. Required with `vault` and not allowed with `credential` or `onePassword`. - `selector` string, required: CSS selector of the input to type into, at most 1024 UTF-8 bytes. - `ref` OnePasswordField: A field of an item in the request's 1Password vault (`onePassword.vault`), read as `op:////[
/]`. The whole reference can be at most 512 bytes of UTF-8. - `item` string, required: The item. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`. - `section` string: The section, if the field is in one. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`. - `field` string, required: The field. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`. It may end with one query, such as `?attribute=otp` (a TOTP field's current code) or `?ssh-format=openssh`: keys are lowercase letters and `-`, values are letters, digits, `_` and `-`, and pairs are joined with `&`. - `pageId` string: CDP target ID of the tab to fill, at most 128 UTF-8 bytes. Pass it, or `pageUrl`, when more than one tab could be the target. Not with `pageUrl`. - `pageUrl` string: Fill the tab whose URL starts with this prefix, at most 2048 UTF-8 bytes, instead of naming its `pageId`. Not with `pageId`. - `frame` object: Target an iframe, such as an embedded login form. Without it, the tab's main frame is filled. - `url` string, required: Fill inside the one frame in the tab whose URL starts with this prefix, at most 2048 UTF-8 bytes. ## Response `200` Success - CredentialFillResponse: What was typed where. Never contains values. - `version` integer: The secret version filled, for `credential` fills only. Absent for `vault` and `onePassword` fills, whose fields each report their own. - `pageId` string, required: CDP target ID of the tab filled. - `origin` string, required: Origin of the frame filled. - `fields` CredentialFillFieldResult[], required: One result per requested field, in request order. - `selector` string, required - `field` string: The vault entry, for vault fills. - `outcome` 'filled' | 'not_found' | 'ambiguous' | 'not_editable' | 'not_accepted', required: `filled`: the input now holds exactly the value. `not_found`: no input matched the selector. `ambiguous`: more than one visible input matched. `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 `maxlength`). Treat outcomes you don't recognize as not filled: more may be added. - `secretId` string, uuid, required: The secret typed into this input, or for a 1Password fill the `op_token` secret the field was read with. - `version` integer, required: The secret version typed, or for a 1Password fill the token version used. - `expiresAt` string, date-time: For a `totp` secret, when the typed code stops being current. Fill again if you submit after it. Not set for 1Password fills. - `reference` string: For a 1Password fill, the reference read: `op:////[
/]`. ## Other responses - `400`: Invalid request body, SECRET_METADATA_INVALID (an invalid `onePassword.allowedOrigins` entry), or CREDENTIALS_UNSUPPORTED_RUNTIME (the session isn't a Firecracker browser session). SECRET_REQUIRES_CUSTOMER_UNWRAP: the secret or vault entry is customer-protected and can't be typed into pages, or a customer-protected 1Password token was passed by name instead of unwrapped. - `401`: Authentication required. - `403`: API_KEY_SCOPE_DENIED, SECRETS_FEATURE_DISABLED, CREDENTIAL_NOT_ATTACHED (the secret, vault or `onePassword` token wasn't attached when the session was created), or CREDENTIAL_ORIGIN_NOT_ALLOWED (the frame isn't on an allowed origin; `details.origin` names it, and nothing was typed). - `404`: Session not found, SECRET_NOT_FOUND, VAULT_NOT_FOUND, VAULT_ENTRY_NOT_FOUND, SECRET_VERSION_NOT_FOUND, CREDENTIAL_PAGE_NOT_FOUND (no tab with this `pageId` or `pageUrl`, or no open tab), or CREDENTIAL_FRAME_NOT_FOUND (no frame URL starts with `frame.url`). - `409`: SECRET_TYPE_MISMATCH (the secret can't be filled, such as an `op_token` named as `credential`, or `onePassword.token` isn't an `op_token`), CREDENTIAL_NOT_READY (no allowed origins or no value uploaded), SESSION_NOT_ACTIVE, CREDENTIAL_PAGE_AMBIGUOUS (pass `pageId` or `pageUrl`; `details.pages` lists each tab's `pageId`, `url` and `title`), CREDENTIAL_FRAME_AMBIGUOUS (more than one frame URL starts with `frame.url`), or the session's runtime isn't ready. SECRET_DIGEST_MISMATCH: the unwrapped 1Password token isn't the one stored for that version. - `422`: SECRET_VALUE_INVALID: the stored value can't be used, such as an invalid TOTP seed; upload a new version. SECRET_ONEPASSWORD_REFERENCE_FAILED: 1Password couldn't resolve a field; `details.selectors` and `details.reasons` (by selector) name the inputs, and nothing was typed. SECRET_ONEPASSWORD_AUTH_FAILED: 1Password rejected the token, or the token is malformed or signs in outside 1password.com, 1password.ca and 1password.eu (or their subdomains), so it wasn't sent. Both carry `details.tokenSecretId` and `details.tokenVersion`. Other SECRET_* codes mean the stored envelope couldn't be opened. - `429`: SECRET_ONEPASSWORD_RATE_LIMITED: 1Password is rate limiting the service account (retryable; `details.tokenSecretId` and `details.tokenVersion`). - `500`: CREDENTIAL_FILL_FAILED or an internal server error. Check `retryable`. - `501`: CREDENTIAL_FILL_UNSUPPORTED: the session's browser predates credential fill. - `502`: CREDENTIAL_FILL_FAILED: the browser couldn't complete the fill. SECRET_ONEPASSWORD_FAILED: 1Password couldn't be reached (retryable; `details.tokenSecretId` and `details.tokenVersion`). - `503`: CREDENTIAL_FILL_TIMEOUT: the session's host couldn't be reached and nothing was filled (retryable). SECRETS_NOT_CONFIGURED or SECRET_KEY_UNAVAILABLE: the session's host can't decrypt secrets. SECRET_ONEPASSWORD_FAILED: 1Password isn't available on the session's host, and nothing was typed (retryable; `details.tokenSecretId` and `details.tokenVersion`). - `504`: CREDENTIAL_FILL_TIMEOUT: the fill wasn't confirmed in time (retryable). ## Changes - **2026-11-10** `94dc06948680`: 1 breaking, 2 info - the `onePassword/token` request property type changed from `string` to no type - added `#/components/schemas/SecretReference, subschema #1` to the `onePassword/token` request property `oneOf` list - removed the pattern `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$` from the request property `onePassword/token` - **2026-10-15** `225d94fe61a0`: 4 info - added the new optional request property `fields/items/ref` - added the new optional request property `onePassword` - added the non-success response with the status `429` - added the optional property `fields/items/reference` to the response with the `200` status - **2026-10-15** `6ca0b00ee564`: 1 info - endpoint added [Operation history](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/changes/api/session/:id/credentials/fill/post.md) --- [API](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api.md) - [All operations](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/revisions/ef089024c533?raw)