Credentials and 2FA

Let an agent sign in with vault credentials and resolve one-time codes, without vault secrets entering its context.

A vault holds the credentials an agent signs in with, one login per item: the sites it applies to and up to five fields. The agent asks for a field such as password, and the session picks the item from the page URL and types the value into the page, outside the agent’s context. No endpoint returns secrets. To start already signed in, use a browser profile.

provider	Where the secrets live	provider_config	token
onepassword	A 1Password vault you own. When an agent fills a field, H fetches the item from 1Password and decrypts it.	{"provider": "onepassword", "op_vault_id": "..."}	A 1Password service account token for that vault. Validated against 1Password, write-only, never returned.
internal	An H-hosted vault: H stores the items you add through the item endpoints.	{"provider": "internal"}	None.

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. When a vault credential matches the current page, the agent is offered a fill_secret_at action to sign in.

• Cloud browsers only, since secrets never leave H’s infrastructure.
• Manage vaults (list, update, rotate a 1Password token, delete, health-check) from the Vaults endpoints, and an H-hosted vault’s items from the item endpoints.

1Password

Python

from hai_agents import Client, CreateEnvironmentRequest_Web, VaultCreateRequestProviderConfig_Onepassword

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

H-hosted

Create the vault, add one item per login, then bind it the same way:

cURL

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": "team-logins", "provider_config": {"provider": "internal"}}' | jq -r .id)

curl -X POST "https://agp.eu.hcompany.ai/api/v2/vaults/$VAULT_ID/items" \
  -H "Authorization: Bearer $HAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Example admin",
    "urls": ["https://example.com/login"],
    "values": {"username": "[e-mail]", "password": "s3cret", "totp": "JBSWY3DPEHPK3PXP"}
  }'

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\"}"

What an item holds

An item carries up to five fields, each a value the agent can fill: username, password, email, totp, and api_key. For totp, fill_secret_at types the current code, never the secret.

In an H-hosted vault, set them in the item’s values. For totp, store the authenticator secret (base32, or an otpauth://totp/ URI).

In 1Password, each one maps to a field on the item. Other fields are ignored:

Field	1Password item field
username	Title contains “username”
password	Password type, title contains “password”
email	Email type, or title contains “email”
totp	One-time password type
api_key	Password type, title contains “api” or “key”

How secrets are matched

Agents never name an item. The page URL picks one item, using the sites stored on it (a 1Password item’s websites, or an H-hosted vault item’s urls), and the agent can fill only that item’s fields:

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, 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 sharing the most leading segments with the page URL wins, then the one with the fewest stored segments the page doesn’t share. Path is never required.	Three hcompany.ai items on page test.hcompany.ai/app/login: path /app beats /, which beats /enterprise.

In an H-hosted vault, two items that still tie resolve to the most recently created one. Store one item per login so matching stays unambiguous.

Handle two-factor authentication

Authenticator apps via a vault

For a TOTP authenticator, store its secret in 1Password or as an H-hosted vault item’s totp value, then bind the vault. On a matching page, the session generates the code from the TOTP secret and fill_secret_at with totp types it in. The agent never sees the code.

Email, SMS, and confirmation links

The SDKs ship a custom tool for this: the agent calls request_otp, your process resolves the code or link, and the session continues with that single value. Pass otp_tool / otpTool in tools with the handler that matches where the code arrives:

Where the code arrives	Handler	Best for
You’re at the keyboard	None: prompts in your terminal (Node.js only in TypeScript)	Debugging at your desk
An inbox you control	imap_otp_handler / imapOtpHandler	Unattended sessions
Slack, an SMS provider, anything else	Your own function, sync or async	Anything your code can reach

Python

import os

from hai_agents import Client
from hai_agents_tools import OtpRequest, imap_otp_handler, otp_tool

inbox = imap_otp_handler(
    host="imap.gmail.com",
    username="[e-mail]",
    password=os.environ["GMAIL_APP_PASSWORD"],
    sender="[e-mail]",  # optional: only mail from this address
)

def from_slack(request: OtpRequest) -> str:
    return slack.ask_user(request.prompt)

client = Client()
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Log in to example.com and check for new notifications.",
    tools=[otp_tool(inbox)],  # or otp_tool() to prompt, otp_tool(from_slack) for your own handler
)
print(result.answer)

Read the code from email

The IMAP handler runs in your process. It polls unread mail (newest first), extracts a code or confirmation link, marks that message read so a retry can’t reuse a stale code, and returns only that value. IMAP credentials never leave your machine, and the agent never sees mailbox contents, subjects, or senders. For Gmail or Google Workspace, use an app password.

Option (Python / TypeScript)	Default	Role
host, username, password	required	IMAP login
port	993	IMAP over TLS
mailbox	"INBOX"	Mailbox to poll
sender	unset	Only consider mail from this address
timeout_s / timeoutMs	2 minutes	Give up (tool error to the agent) after this long
poll_interval_s / pollIntervalMs	5 seconds	Delay between polls
max_age_s / maxAgeMs	15 minutes	Ignore unread mail older than this
mark_seen / markSeen	on	Mark the matched message read
code_pattern / codePattern	built-in heuristics	Override extraction. The first capture group (or the whole match) is the code

What the agent sends

Your handler receives the tool’s fixed input schema as an OtpRequest:

Field	Required	Meaning
prompt	yes	Human-readable ask, for example “Enter the 6-digit code sent to j***@example.com”
kind	no	"code" (default), or "link" for a full confirmation URL
source	no	Where it was sent, for example "email", "sms", "authenticator app"

Return a non-empty string. An empty value fails as a tool error, so the agent can retry or stop cleanly.