---
title: "Authorise one credential fill. Requires the bridge credential *and* an agent JWT — neither alone is sufficient."
method: POST
path: "/v1/agents/{id}/browser/fills"
tags: ["Browser Bridge"]
---

# Authorise one credential fill. Requires the bridge credential \*and\* an agent JWT — neither alone is sufficient.

`POST /v1/agents/{id}/browser/fills`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/agents/{id}/browser/fills`
- Auth: HTTP bearer

## Headers

- `x-1claw-bridge-credential` string, required
- `x-1claw-bridge-version` string, required

## Request body

- object
  - `session_id` string, uuid, required: Must match the session the presented bs_ token opened.
  - `binding_id` string, uuid, required
  - `frame_id` string, required: The target the fill is for. Recorded on the grant.
  - `generation` integer, required: The bridge's navigation counter. Compared again at consume: a navigation in between means the page decided about is no longer the page in front of the bridge.
  - `form_action_origin` string: Where the form would POST. Checked as well as the two origins — a login form on an allowed page can still submit to somebody else's host. Absent is not treated as 'same as the tab'; it denies.
  - `form_path` string, required: Path of the form being filled, checked against the binding's fingerprint.
  - `field_names` string[], required: Field names on that form. Every field the fingerprint expects must be present; extra fields are fine, since sites add hidden inputs.
  - `redirect_chain` string[], required: Hosts the login has redirected through, in order. Each is checked against the binding's allowed hosts union its sso hosts.
  - `current_generation` integer, required: The target's generation now. A mismatch with `generation` means the page moved and the fill is denied.
  - `tab_origin` string, required: Origin of the tab being driven. Checked against the binding's allowed and sso hosts by exact host match.
  - `frame_origin` string, required: Origin of the frame holding the form. Checked separately — a credential typed into an allowed tab can still land in an attacker's iframe.

## Response `200`

A grant, a denial, or a pending approval. Never a secret.

- object
  - `kind` 'grant'
  - `grant_id` string, uuid: Single-use, short-lived, redeemable only by the session it was issued to.
  - `binding_id` string, uuid
  - `expires_at` string, date-time
  - `login_url` string: The bridge navigates here itself. An agent-supplied URL would be the agent choosing who receives the password.

## Other responses

- `400`: Missing or unsupported bridge version
- `403`: Only one of the two required credentials was presented, an origin is not on the binding's allowlist, or the fill velocity cap was hit
- `404`: No such binding for this org

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)