Vaults - H Platform Docs

A vault links your organization to an external secrets provider so an agent can sign in to sites without credentials passing through the API. The agent pulls the matching secret when it needs it. Secrets never travel through your requests and no endpoint returns them. 1Password is the only supported provider.

Field	Required	Description
`name`	Yes	Label for the vault config.
`provider_config.op_vault_id`	Yes	The 1Password vault to read credentials from.
`provider_config.provider`	No	Default `onepassword`, the only supported value.
`token`	Yes	A 1Password service account token for that vault. Validated against the provider, write-only, never returned.

Set up a vault

A vault does nothing until a browser environment binds it with vault_id. Create the vault, then bind it inline in an agent’s environments or on a catalog environment:

VAULT_ID=$(curl -sX POST https://agp.eu.hcompany.ai/api/v2/vaults \
  -H "Authorization: Bearer $HAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "prod-1password",
    "provider_config": {"provider": "onepassword", "op_vault_id": "abcd1234efgh5678"},
    "token": "ops_eyJ..."
  }' | jq -r .id)

curl -X POST https://agp.eu.hcompany.ai/api/v2/environments \
  -H "Authorization: Bearer $HAI_API_KEY" -H "Content-Type: application/json" \
  -d "{\"id\": \"signed-in-browser\", \"kind\": \"web\", \"vault_id\": \"$VAULT_ID\"}"

from hai_agents import Client, OnePasswordConfig

client = Client()
vault = client.vaults.create_vault(
    name="prod-1password",
    provider_config=OnePasswordConfig(op_vault_id="abcd1234efgh5678"),
    token="ops_eyJ...",
)
client.environments.create_environment(id="signed-in-browser", kind="web", vault_id=vault.id)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();
const vault = await client.vaults.createVault({
  name: "prod-1password",
  providerConfig: { opVaultId: "abcd1234efgh5678" },
  token: "ops_eyJ...",
});
await client.environments.createEnvironment({ id: "signed-in-browser", kind: "web", vaultId: vault.id });

Then run sessions as usual with an agent that uses this browser. When a vault credential matches the current page, the agent is offered a fill_secret_at action to sign in.

The vault must belong to your organization.
Cloud browsers only (host: "cloud", the default). Secrets are resolved and typed inside H’s infrastructure and never leave it, so vault_id with host: "user_device" is rejected.
Leave vault_id unset to run without secret access.
Manage vaults (list, update, rotate the token, delete, health-check) from the Vaults endpoints.

How secrets are matched

Agents never name a 1Password item. The page URL picks the item:

Rule	Behavior	Example (page `test.hcompany.ai`)
Domain gating	Eligible only if the page hostname equals, or is a subdomain of, a site stored on the item.	`hcompany.ai` item: eligible. `prod.hcompany.ai` item (sibling): not eligible.
Closest host wins	Among eligible items with the same field, the most specific hostname match wins. Exact host beats parent domain. Deeper subdomain beats shallower.	`test.hcompany.ai` item beats `hcompany.ai` item.
Path breaks ties	Equal hostname matches: the stored path that best prefixes the page URL wins. Path is never required.	Two `hcompany.ai` items on page `test.hcompany.ai/app/login`: path `/app` beats `/`.

Store one item per site so matching stays unambiguous. Related: Two-factor authentication (one-time codes at login), Browser profiles (start signed in from saved cookies).