Five tools handle credentials, and two more type them into web pages. These seven tools keep plaintext out of their arguments and results: the model gets a reference, and SoAI does the typing.
This page covers the tool workflow and storage details. Passwords and credential tools explains how this boundary differs from WebUI passwords and generated strings, and what remains at risk after a credential is protected from the model.
In the SoAI WebUI, make a vault tool available by selecting Chat configuration in the chat header, then
Tools. Turn on Tools enabled, choose the tool for the required mode, and select
Save. The account needs MCP usage (MCP_USE) and the selected model must support tool
calling. Credential collection and browser autofill normally require the authenticated SoAI WebUI because the dialog is
where the secret is entered. A messaging account can allow a plaintext provider reply for a vault credential
request, but that option has a different security boundary described below.
Credentials in chat
An agent could use ask_user to ask for a password, and the answer would land in the conversation. From
there it goes into the prompt on every following turn, into the stored transcript, into any export of that
conversation, and out to the model provider if the model is remote. A password pasted into a chat is a password you
have to change.
The vault tools break that chain. You type the credential into a SoAI dialog, SoAI keeps it, and the model receives an opaque handle. The handle is useless to anything except a later SoAI tool call.
Collecting a credential
Two tools open the prompt, and they differ in what they are for.
| Tool | Use it for |
|---|---|
vault_login_request |
A website login, tied to a url. Offers to save, and takes a
label_suggestion for the saved entry. Flagged for approval.
|
vault_secret_request |
Any credential, with a custom title and message. Saving to the vault is
offered by default; a call can set allow_save_to_vault: false to remove that option.
|
Either way a dialog appears in the chat with Username and Password fields, a Label, and a Save this credential checkbox when saving is on offer. Ticking it requires a label, since that is how you will recognise the entry later. Submit sends it, Cancel refuses, and the agent is told which happened without learning anything else.
What comes back to the model is a secret_handle: a random token that names the credential without
revealing it. SoAI keeps handles in memory for ten minutes and enforces caps of 200 per user and 5,000 across the
installation. Creating too many evicts the oldest handles. A handle from one conversation does not work in another.
A successful browser_autofill_secret call consumes its handle, so the agent must request a new one
before another fill.
Credential requests in messaging conversations
When an agent in a Discord, Telegram, or WhatsApp conversation requests a credential, SoAI sends a secure link to
the matching conversation in the authenticated Chat page. Secret questions use the same secure path. The link
requires an HTTPS
SERVER.PUBLIC_ORIGIN that the signed-in
owner of the messaging account can reach. It can remain private behind a local network or VPN; the messaging
provider does not open this link. The owner opens it and completes the secure prompt in Chat.
The messaging account option Allow plaintext secret replies applies only to vault credential requests (not ordinary secret questions). When it is on, the remote user may reply with the credential in the provider conversation. SoAI does not save that plaintext reply to the vault, but the provider may retain it in message history, notifications, or its own systems. Keep the option off when the secure Chat link is available. See Connect messaging apps to SoAI for messaging account settings and remote interaction replies.
The caps come from
TOOLS.MCP.SECRET_PROMPT.HANDLE_STORE_MAX_PER_USER
and
TOOLS.MCP.SECRET_PROMPT.HANDLE_STORE_MAX_TOTAL. To change them, an administrator with Configuration changes (CONFIG_PATCH) selects
Open settings menu at the right of the header, then Settings. Select
Advanced in the Settings page header. The page becomes Advanced settings and the
control changes to Basic. Search for the key, edit it, and select Save.
Vault storage
SoAI encrypts saved credentials with Fernet before writing them to the database. The key file comes from
SYSTEM.PATHS.SYSTEM_ENCRYPTION_KEY, and SoAI resolves a relative value under
SYSTEM.PATHS.SYSTEM_DATA. The default path is data/secret.key.
The file can contain several Fernet keys, one nonempty key per line. SoAI encrypts new values with the first key and tries every listed key while decrypting. SoAI has no WebUI rotation control and does not rewrite existing vault rows automatically. A staged rotation therefore keeps older keys in the file until no stored value depends on them; removing one earlier makes those values unreadable.
Back that key up separately from the database. A database backup without the key is a file of unrecoverable ciphertext, and there is no recovery path: nobody can decrypt those entries, including you.
To clear everything, the signed-in user selects Open settings menu at the right of the header, then Settings and Reset, and uses Password manager. It deletes every saved credential for the signed-in account and invalidates that account's live handles. There is no undo.
Reading the vault
vault_list lists saved credentials and vault_search finds them by label. Both return
metadata only: labels, identifiers, and dates, never a password. That is enough for an agent to say
I have a saved login for that site and to pass the right ID to an autofill tool.
vault_delete removes one by credential_id. It is destructive and flagged for approval, so
Plan mode refuses it and you get asked first.
Filling in a login
Two browser tools do the typing, and neither one receives the secret as an argument.
-
browser_autofill_secretuses asecret_handlefrom one of the request tools, for a credential you entered for this task. -
browser_autofill_vaultuses acredential_idfrom the vault, for one saved earlier.
Both take the page url, optional username_ref and password_ref pointing at
the fields from a browser snapshot, and submit to press the login button afterwards. Leave the refs out
and SoAI finds the username and password fields itself, which is usually right and occasionally is not. On a page
with several forms, pass the refs.
browser_navigate can also use a secret_handle for HTTP Basic Auth. It consumes the handle
when it resolves the credentials for that navigation.
The request tools bind each credential to the collection URL's origin. Before autofill, SoAI compares the target's scheme, IDNA-canonical hostname, and explicitly written port. A lookalike domain, another scheme, or a different port does not match.
SoAI stores approval for these two tools per origin rather than per tool. Approving a fill on one site does not approve it anywhere else. When SoAI cannot determine the origin from the arguments, it asks every time and stores nothing.
Protection boundary
The vault path keeps secrets out of the prompt, transcript, and request/autofill tool arguments and results. It encrypts them at rest and prevents the autofill tools from typing them into a different origin.
This protection applies to the vault and autofill path, not to every browser capability. The default-enabled
browser_eval tool can run arbitrary JavaScript in the page and can read a filled password field while
its value remains in the DOM. Disable
TOOLS.MCP.BROWSER.JS_EVAL_ENABLED
and leave browser_eval out of the selected tools when the model must not be able to retrieve a filled
credential.
Approval authorizes the agent to use the credential. After login, every browser tool in that session can act as the account. Anyone who obtains both the database and the encryption key can decrypt saved credentials. The destination site and its scripts receive the submitted credential and control what happens after login.
Treat approving an autofill as handing over the account for the rest of that session, and see Browser automation tools for what that session can then do.