Sessions & HITL
Hand over an account the agent created
The email and password a run signed up with when the prompt gave none — for logins the agent created only, to a key granted accounts:reveal, audited on every call.
reveal_account
What it is
The job: Give the owner of a newly provisioned account the login the agent signed up with.
A run that creates an account with no password in the prompt signs up with the tenant’s default new-account password, or a strong one generated for that site, and files the login under the site. To USE that login you never need its value — pass its label as `account` on a run. When a person has to have it — the account is theirs — this is how you read it.
It is the only call that returns a credential value, so it is narrow on purpose. It returns only logins whose origin is `agent`, never one a person saved; it answers only a key created with “Can read passwords of accounts the agent creates” (scope `accounts:reveal`, never part of a default key and never implied by a legacy one); and every call is written to the audit log with the key, the login and the host.
The call
Call it exactly like this.
Copied from the tool's registration and the route handler — not paraphrased.
// MCP tool call — server "twin-browser"
{
"tool": "reveal_account",
"arguments": {
"host": "example.com"
}
}curl -X POST https://twin-browser.com/api/v1/accounts/reveal \
-H "Authorization: Bearer $TWIN_API_KEY" \
-H "content-type: application/json" \
-d '{"host":"example.com"}'A key without the accounts:reveal scope gets 403 scope_required, and a login a person saved answers 404 exactly like one that does not exist.
| Parameter | Type | What it does |
|---|---|---|
| host | string | The site, as list_accounts returns it. With no label, the newest login the agent created there. |
| label | string | Which login on that host — the list_accounts label. |
| id | string | Or the login id, instead of host and label. |
Returns
{ "host": "example.com", "label": "jo-example-com", "email": "jo@example.com",
"password": "…", "origin": "agent" }What it costs
Free
No browser and no credits. Rate-limited per tenant, and audited.
See the full rate cardWhich one
When a different tool is the right call.
The honest answer is often the neighbouring tool. These are the trades.
list_accountslist_accounts finds the login (origin "agent") and its label; reveal_account reads it.
list_accountsset_new_account_defaultsSet a default instead, and every account the agent creates uses a password you already know.
set_new_account_defaultsQuestions
reveal_account, answered.
- Why can it not return a login I saved myself?
- Because you already hold that one, and an API that can read every stored password turns one leaked key into every account. The exception exists only for a password nobody else holds.
Keep going