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. It is validated against the provider before it is stored, kept write-only, and never returned by any endpoint.
Manage vault configs through the Vaults endpoints: create, list, retrieve, update, rotate the token, delete, and health-check.

​
Bind the vault to a browser

Creating a vault is not enough on its own: nothing uses it until you bind it to a Browser environment by setting the browser’s vault_id field to the vault’s id. Set it inline in an agent’s environments list, or on a catalog environment when you create or update it: 
{
  "id": "signed-in-browser",
  "kind": "web",
  "vault_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
Once bound, sessions running on that browser offer the agent a fill_secret_at action whenever a credential in the vault matches the page it is on. The vault must belong to your organization; 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.