Skip to content
Docs menu

Saved logins and cards

Save a login, a card or a text once, and an agent types it into pages on its computer without ever seeing it. Where values are stored, which pages may receive them, and how to revoke.

View .md

Most sign-ins on a computer are done by a person once, during a takeover, and stay in the computer's browser profile. A saved login is for the rest: a password an agent has to type again, a card at a checkout, an API key that a site wants in a form. You save it once. The agent writes a handle in place of the value, and the value is typed into the page without the model ever reading it.

What you can save

Kind Holds Handles
login username, password {{secret:github.username}}, {{secret:github.password}} for the label github
card number, expiry (MM/YY), cvc, optional name {{secret:visa.number}}, .expiry, .cvc, .name
text one value {{secret:pin}}

A label is 1 to 40 letters, digits, - or _. A card is checked for what a typo breaks (digits, check digit, month, code length), so a wrong one fails when you save it and not at a checkout.

Where it may be typed

Every saved login names the origins it may be typed into: one to ten https origins, each an exact origin (https://github.com, https://app.example.com:8443) or a domain and its subdomains (https://*.example.com).

  • A sibling subdomain matches only under *.: https://app.example.com does not allow https://www.example.com.
  • http, paths, user names, IP addresses and bare top-level domains (https://*.com) are refused.
  • A wildcard is for the default port; name another port on its own.
  • The check is made on the origin of the page frame the field is in, not on what the agent says it is doing. A field in an embedded frame is checked against that frame's own origin, so a card form inside a payment provider's frame works only when that provider's origin is in the card's origins.

Who a login applies to

Scope Applies to
org (default) every computer of the organisation
agent:<id> that agent's computers: its dedicated computer and the shared computers it belongs to
seat:<computer id> one computer

If two logins share a handle, the most specific one wins: the computer's own, then the agent's, then the organisation's. On a shared computer every member shares one browser profile and its cookies, so an agent's login applies to the shared computers it belongs to for all their members.

Org admins and owners manage every scope. The owner of an agent manages that agent's logins, and the person who made a computer manages its own. Everyone who can read computers sees the list: label, kind, origins, scope, handles and when it was last used. An agent sees only what applies to its own computers. An agent never saves or revokes a login.

Save and revoke

In the console, a computer's page and the Computers settings have a Saved logins and cards section. Agents and scripts use the API or the tools:

Route Tool
GET /api/workspace/computers/credentials[?scope=&seat_id=] computers_credential_list
POST /api/workspace/computers/credentials {scope?, label, kind, origins, values} computers_credential_create
DELETE /api/workspace/computers/credentials/{id} computers_credential_delete

Revoking deletes the row and the sealed value with it, at once. Anything the daemon is holding for a use already in flight is dropped within a minute.

Where values live and who can read them

  • Sealed in the cloud vault. The values are encrypted with AES-256-GCM under a key derived for your organisation and the purpose computer, with the login's id as additional authenticated data, the same envelope as provider keys (VENOM_VAULT_KEYS). A row copied to another login, another purpose or another organisation does not open.
  • Write-only. No API, tool, export, console page, audit row or log returns a value. A response is built from columns that exclude the sealed value, and the tests search every response shape, the audit log and the server's logs for the values they saved.
  • Opened for one use. Only the daemon that hosts the computer can ask for a value, for one field at a time, for a session the cloud knows is bound to that daemon at that epoch, and only when the login applies to that computer and the origin of the frame being typed into is one the login names. The answer is no-store. A refused ask is also written to the audit log.
  • Never in the model's context. The model sees handles. Tool results say Typed {{secret:NAME}} (a secret; its value is not shown), page reads show (secret: NAME), screenshots hide fields that hold one, and the scrubber replaces a value that would appear anywhere else.
  • Audited. Saving and revoking write computers.credential_created and computers.credential_deleted with the label, kind, scope and origins. Every use writes computers.credential_used (the computer, the session, the origin, the login id and the field, never the value), and a refusal writes computers.credential_refused with the reason (origin, scope, field). The row is written before the value leaves the cloud: if it cannot be written, nothing is returned.
  • Cards ask. Every use of a card is an approval: the person sees the merchant origin and the card label first.

What this does not protect against

  • A page you allow a login on can read what it receives. List only origins you trust with that login.
  • Anyone who can take control of a computer can type into its browser. Control is a lease that needs write access.
  • Someone who holds the vault keys and the database can open the values, as for every key the cloud stores for you (ADR 0028). Self-hosting the cloud keeps the keys on your side.