> ## Documentation Index > Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Fill a credential > Type a secret's or a vault's values into a page in the session, without returning them. See the [credential fill guide](/docs/sessions/credentials) for SDK examples and how to choose the page and fields. ## OpenAPI ````yaml openapi.json POST /api/session/{id}/credentials/fill openapi: 3.0.1 info: title: Hyperbrowser API version: 1.0.0 servers: - url: https://api.hyperbrowser.ai description: Production server security: [] paths: /api/session/{id}/credentials/fill: post: summary: Fill a credential description: >- Types a secret, or a vault's entries, 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. A `totp` secret types the code current at fill time. A fill is safe to retry. Without `pageId`, Hyperbrowser keeps the tabs whose URL starts with `pageUrl` (if given) and uses the tab left if there's only one, even if it isn't on an allowed origin (403 CREDENTIAL_ORIGIN_NOT_ALLOWED). Otherwise it prefers the tabs on the allowed origins, when there are any, then the only visible one; otherwise it returns 409 CREDENTIAL_PAGE_AMBIGUOUS listing the tabs. Requires an active Firecracker browser session created with these secrets 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`. operationId: fillSessionCredential parameters: - name: id in: path required: true schema: type: string format: uuid description: Session ID. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CredentialFillParams' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CredentialFillResponse' '400': description: >- Invalid request body, CREDENTIALS_UNSUPPORTED_RUNTIME (the session isn't a Firecracker browser session), or VAULT_SOURCE_INVALID (1Password vaults can't be filled). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '403': description: >- API_KEY_SCOPE_DENIED, SECRETS_FEATURE_DISABLED, CREDENTIAL_NOT_ATTACHED (the secret wasn't attached when the session was created, or a vault entry now points at another secret), or CREDENTIAL_ORIGIN_NOT_ALLOWED (the frame isn't on an allowed origin; `details.origin` names it, and nothing was typed). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '404': description: >- 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`). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '409': description: >- SECRET_TYPE_MISMATCH (the secret can't be filled, such as 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. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '422': description: >- SECRET_VALUE_INVALID: the stored value can't be used, such as an invalid TOTP seed; upload a new version. Other SECRET_* codes mean the stored envelope couldn't be opened. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '500': description: >- CREDENTIAL_FILL_FAILED or an internal server error. Check `retryable`. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '501': description: >- CREDENTIAL_FILL_UNSUPPORTED: the session's browser predates credential fill. CREDENTIAL_VALUE_UNSUPPORTED: the session's host can't produce this value type yet. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '502': description: 'CREDENTIAL_FILL_FAILED: the browser couldn''t complete the fill.' content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '503': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '504': description: >- CREDENTIAL_FILL_TIMEOUT: the fill wasn't confirmed in time (retryable). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' security: - ApiKeyAuth: [] components: schemas: CredentialFillParams: type: object properties: credential: type: string minLength: 1 maxLength: 255 description: >- 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: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$ description: >- A stored 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. fields: type: array minItems: 1 maxItems: 16 items: $ref: '#/components/schemas/CredentialFillField' description: The inputs to type into. Each selector may appear once. pageId: type: string minLength: 1 description: >- 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: type: string minLength: 1 description: >- Fill the tab whose URL starts with this prefix, at most 2048 UTF-8 bytes, instead of naming its `pageId`. Not with `pageId`. frame: type: object properties: url: type: string minLength: 1 description: >- Fill inside the one frame in the tab whose URL starts with this prefix, at most 2048 UTF-8 bytes. required: - url additionalProperties: false description: >- Target an iframe, such as an embedded login form. Without it, the tab's main frame is filled. required: - fields additionalProperties: false description: Provide exactly one of `credential` and `vault`. CredentialFillResponse: type: object description: What was typed where. Never contains values. properties: version: type: integer description: The secret version filled, for `credential` fills. pageId: type: string description: CDP target ID of the tab filled. origin: type: string description: Origin of the frame filled. fields: type: array description: One result per requested field, in request order. items: $ref: '#/components/schemas/CredentialFillFieldResult' required: - pageId - origin - fields SecretErrorResponse: type: object properties: code: type: string description: Machine-readable error code, such as SECRET_NOT_FOUND. message: type: string error: type: string description: >- Set instead of `code` by authentication and API key scope errors (API_KEY_SCOPE_DENIED). requiredScopes: type: array items: type: string description: The scope the API key is missing, with API_KEY_SCOPE_DENIED. retryable: type: boolean description: >- Whether repeating the same request can succeed. Set on delivery errors. details: type: object additionalProperties: true description: >- Extra information for some codes, such as `origin` for CREDENTIAL_ORIGIN_NOT_ALLOWED or `pages` for CREDENTIAL_PAGE_AMBIGUOUS. description: >- HTTP failure. Secret errors include `code` and `message`; request validation errors include only `message`; API key scope errors include `error`, `message` and `requiredScopes`. CredentialFillField: type: object properties: field: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]*$ maxLength: 256 description: >- With `vault`, the entry to type, such as `PASSWORD`. Required with `vault` and not allowed with `credential`. selector: type: string minLength: 1 description: CSS selector of the input to type into, at most 1024 UTF-8 bytes. required: - selector additionalProperties: false CredentialFillFieldResult: type: object properties: selector: type: string field: type: string description: The vault entry, for vault fills. outcome: $ref: '#/components/schemas/CredentialFillOutcome' secretId: type: string format: uuid description: The secret typed into this input. version: type: integer description: The secret version typed. expiresAt: type: string format: date-time description: >- For a `totp` secret, when the typed code stops being current. Fill again if you submit after it. required: - selector - outcome - secretId - version CredentialFillOutcome: type: string enum: - filled - not_found - ambiguous - not_editable - not_accepted description: >- `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. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.