Skip to main content
When an agent needs to sign in to a site or service, you don’t pass the credentials through the API. Instead you register a vault (a link between your organization and an external secrets provider), and the agent pulls the right secret at the moment it needs it. Secrets never travel through your API requests and are never returned by any endpoint. Today the only provider is 1Password.

​
What a vault stores

A vault config records two things:
  • op_vault_id: which 1Password vault to read credentials from.
  • A service account token authorizing access to that vault.
Manage vault configs through the Vaults endpoints: create, list, retrieve, update, rotate the token, delete, and health-check.

​
Set up a vault

Creating a vault is not enough on its own: nothing uses it until you bind it to a Browser environment.
1

Create a vault

Register the 1Password vault and a service account token that grants access to it. The token is validated against the provider, kept write-only, and never returned. See Create a vault for the full field list.
2

Bind it to a browser

Set the browser’s vault_id to the vault’s id, inline in an agent’s environments list or on a catalog environment. The vault must belong to your organization.Vaults are only supported on cloud-hosted browsers (host: "cloud", the default). Secrets are resolved and typed inside H Company infrastructure and never leave it, so a browser running on your own device cannot bind a vault; setting vault_id with host: "user_device" is rejected.
3

Run with secret access

Run a session against an agent using that browser as usual. Whenever a credential in the vault matches the page the agent is on, the session offers it a fill_secret_at action to sign in. Leave vault_id unset to run without secret access.

​
How secrets are matched

Agents never name a 1Password item directly. When an agent fills a credential, the item is selected automatically from the page’s URL:
  • Domain gating: an item is eligible only if the page’s hostname equals, or is a subdomain of, one of the item’s stored sites. An agent on test.hcompany.ai can use an item stored for hcompany.ai (a parent domain), but not one stored for prod.hcompany.ai (a sibling).
  • Closest host wins: when several eligible items hold the same field, the one whose hostname matches the page most specifically is chosen. An exact host beats a parent-domain match, and a deeper subdomain beats a shallower one.
  • Path breaks ties: if two items match the hostname equally well, the one whose stored path best prefixes the page URL wins. Path is only a tiebreaker, never a requirement.
Store one item per site so matching stays unambiguous.