Skip to content
Browsa
  1. Guides
  2. Secrets

Secrets: let agents log in without seeing passwords

Save a login, a 2FA seed or an API key once. Agents use it by name. Browsa types the value at the keystroke, only on the sites you allow. The model never gets the value.

What a secret is

One vault per workspace. Each secret has a name such as GITHUB_LOGIN, a type, and the sites it may be typed on.

TypeHoldsFor
loginUsername, password, optional 2FA seedSigning in
totp
A 2FA seed (base32 or otpauth://)
One-time codes on their own
valueOne line, 3 to 4096 charactersAPI keys, PINs, account numbers

Allowed sites (origins) are required, up to 10. Always https.

You writeTyped on
example.comexample.com and every subdomain
app.example.comThat host only
https://app.example.comThat host only
*.example.comexample.com and every subdomain

No IP addresses, ports, paths or other wildcards. *.co.uk and *.github.io are refused. Values are write-only: no call returns them, only username_masked (re…).

Create one

In the dashboard

Settings, Secrets, then Add secret. Pick the type, fill in the name, sites and value, then Save secret. The page seals each value in your browser before it is sent.

With the API

POST /v1/secrets. The browsa SDKs (0.5.0) have no secrets methods yet, so Python and TypeScript call the endpoint directly.

curl https://browsa.io/v1/secrets \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GITHUB_LOGIN",
    "type": "login",
    "origins": ["github.com"],
    "description": "Bot account for the release checks",
    "username": "release-bot",
    "password": "not-a-real-password-123",
    "totp_secret": "JBSWY3DPEHPK3PXP"
  }'

The answer is the secret without its values:

201
{
  "id": "7b0c2f4e-…",
  "name": "GITHUB_LOGIN",
  "type": "login",
  "description": "Bot account for the release checks",
  "origins": ["https://*.github.com"],
  "username_masked": "re…",
  "has_value": true,
  "has_totp": true,
  "totp": {"digits": 6, "algorithm": "SHA1", "period": 30},
  "placeholders": ["GITHUB_LOGIN:username", "GITHUB_LOGIN:password", "TOTP:GITHUB_LOGIN"],
  "last_used_at": null
}

The description is shown to the model: say what the secret is for, never the value. Lower-case names are upper-cased.

From a .env file

Every line becomes a value secret, with one list of sites for the whole file. Up to 100 lines, in one transaction. In the dashboard: Import .env.

Terminal
jq -Rs '{env: ., origins: ["app.example.com"], on_conflict: "skip"}' .env |
  curl https://browsa.io/v1/secrets/import \
    -H "X-API-Key: $BROWSA_API_KEY" \
    -H "Content-Type: application/json" \
    -d @-

on_conflict: fail (default, nothing is written when a name exists), skip or overwrite. Lines are NAME=value, with optional export, quotes and # comments.

Seal values on your side

For the security-minded: encrypt each value before it leaves your machine, so it is never readable in transit, even behind a proxy that terminates TLS. Get the keypair, seal each field with HPKE (RFC 9180, base mode), send sealed_<field> and keypair_id.

Suite
DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-256-GCM. Empty AAD.
info
The keypair's info_prefix plus the field name: username, password, totp_secret, value or env.
Format
base64(enc || ciphertext)
Rotation
Every 7 days. A retired keypair works 24 more hours, then KEYPAIR_UNKNOWN: fetch it again.
# pip install pyhpke requests
import base64, os
import requests
from pyhpke import AEADId, CipherSuite, KDFId, KEMId

API = "https://browsa.io/v1"
H = {"X-API-Key": os.environ["BROWSA_API_KEY"]}
kp = requests.get(f"{API}/secrets/keypair", headers=H).json()

suite = CipherSuite.new(KEMId.DHKEM_X25519_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES256_GCM)
pk = suite.kem.deserialize_public_key(base64.b64decode(kp["public_key"]))


def seal(field, value):
    enc, ctx = suite.create_sender_context(pk, info=(kp["info_prefix"] + field).encode())
    return base64.b64encode(enc + ctx.seal(value.encode())).decode()


requests.post(f"{API}/secrets", headers=H, json={
    "name": "GITHUB_LOGIN",
    "type": "login",
    "origins": ["github.com"],
    "sealed_username": seal("username", "release-bot"),
    "sealed_password": seal("password", os.environ["GITHUB_BOT_PASSWORD"]),
    "keypair_id": kp["id"],
}).raise_for_status()

The info binds a sealed field to your workspace and to the field: a copied blob does not open elsewhere. Send a field plain or sealed, not both.

Use it in a task

Two steps: attach the secret to the run, then refer to it in the task text. Only attached secrets can be typed; text alone never attaches one.

In the dashboard

On the Agents page, open Secrets under the task box and tick the secret. Then name it in the task: Sign in to github.com with {{secret:GITHUB_LOGIN}}.

Or type secrets. in the task box and pick one from the list. Choosing it ticks it for you.

With the API

Pass names or ids in secret_ids, up to 20.

curl https://browsa.io/v1/tasks \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Sign in to github.com with {{secret:GITHUB_LOGIN}} and list my open pull requests.",
    "llm": "browsa",
    "secret_ids": ["GITHUB_LOGIN"]
  }'

The same secret_ids works on POST /v1/auto (always runs the agent), POST /v1/sessions/{id}/messages (per message), schedules and recipe runs. The finished job lists them as secrets_used. A run with secrets has no evaluate (script) action.

Reference syntax

In the textTypes
{{secret:NAME}}The secret. For a login, the agent picks username or password per field
{{secret:NAME:username}}A login's username
{{secret:NAME:password}}A login's password, only into a password field
{{totp:NAME}}The current one-time code
%NAME%
Same as {{secret:NAME}} when NAME is a secret; other %TEXT% stays text
  • Not attached. A reference to a workspace secret missing from secret_ids is 400 SECRET_NOT_ATTACHED.
  • Unknown. {{secret:NAME}} for a name the workspace does not have is 400 SECRET_NOT_FOUND.
  • Plain words work too. The agent is told the name, type, description and sites of every attached secret.

Short form: secrets.NAME

The preferred form. The older forms above keep working.

In the textSame as
secrets.NAME
{{secret:NAME}}
secrets.NAME.username
{{secret:NAME:username}}
secrets.NAME.password
{{secret:NAME:password}}
secrets.NAME.totp
{{totp:NAME}}
Terminal
curl https://browsa.io/v1/tasks \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Sign in to github.com as secrets.GITHUB_LOGIN.username with secrets.GITHUB_LOGIN.password, enter secrets.GITHUB_LOGIN.totp, then list my open pull requests.",
    "llm": "browsa",
    "secret_ids": ["GITHUB_LOGIN"]
  }'

Leave GITHUB_LOGIN out of secret_ids and the call answers 400 SECRET_NOT_ATTACHED: "add GITHUB_LOGIN to secret_ids". In the dashboard, typing secrets. lists your secrets, and choosing one attaches it.

2FA codes

Save the seed as totp_secret on a login, or as a totp secret of its own. Browsa computes the code (RFC 6238) at the keystroke. The model only sees TOTP:NAME, and the codes are masked like values.

Terminal
curl https://browsa.io/v1/secrets \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SHOP_2FA",
    "type": "totp",
    "origins": ["shop.example.com"],
    "value": "otpauth://totp/Shop:bot?secret=JBSWY3DPEHPK3PXP&issuer=Shop"
  }'
  • Seed. Base32, or the otpauth://totp/ link behind the setup QR code.
  • Check first. Send totp_code, the code your authenticator shows now. A wrong seed is refused with TOTP_CODE_MISMATCH and nothing is saved.
  • Options. digits 6 to 8, algorithm SHA1, SHA256 or SHA512, period 15 to 120 s. Defaults 6, SHA1, 30 s. A link's own settings win.

Robots

A robot lists its secrets in settings.secrets, by name, up to 20. Every row of every run attaches them, and recording (Try) types them as {{secret:NAME}} tokens, never values. In the dashboard: the robot's Settings.

curl -X PATCH https://browsa.io/v1/robots/ROBOT_ID \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"model": {"llm": "browsa"}, "secrets": ["SHOP_LOGIN"]}}'

settings replaces all of the robot's settings, so send the parts you keep. The TypeScript SDK (0.5.0) does not send settings.secrets yet: use the API. GET /v1/robots/{id} adds settings_warnings when a secret is missing (SECRET_NOT_FOUND), has no sites (SECRET_NO_ORIGINS) or cannot be typed on the robot's site (SECRET_ORIGIN_MISMATCH).

Schedules and recipe runs

A schedule keeps the ids. Each run reads the current value, so a changed password needs no edit.

curl https://browsa.io/v1/schedules \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly sign-in check",
    "interval_seconds": 86400,
    "task": "Sign in to github.com with {{secret:GITHUB_LOGIN}} and report the notification count.",
    "llm": "browsa",
    "secret_ids": ["GITHUB_LOGIN"]
  }'

A recipe holds {{secret:NAME}} tokens in its type steps. A direct run attaches them with secret_ids (the SDKs' run_recipe and runRecipe do not send it yet):

Terminal
curl https://browsa.io/v1/recipes/RECIPE_ID/run \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {}, "secret_ids": ["SHOP_LOGIN"], "wait": 60}'

A token resolves only in a type step, on the secret's sites. In a URL or a fetch body the step fails with SECRET_NOT_ALLOWED.

MCP

With the Browsa MCP server (@browsa/mcp 0.6.0 and later), your assistant drives the page itself. Two tools cover secrets:

secrets
Names, types, sites and references. Never values.
act with secret
Types a secret into one field, in place of text.
Tool call
{"action": "type", "id": 14, "secret": "GITHUB_LOGIN:password"}

The answer echoes type [14] secret GITHUB_LOGIN:password (hidden). A value later read from the page shows as <secret>GITHUB_LOGIN:username</secret>. The model never sees a value. References: NAME, NAME:username, NAME:password, TOTP:NAME. On another site the answer starts secret_origin and nothing is typed.

The same works on the API, POST /v1/agents/{id}/act, and in Python: c.act(agent_id, "type", id=14, secret="GITHUB_LOGIN:password").

Save logins the agent creates

When an agent signs up for an account, Browsa generates the password. The model never sees it. When the sign-up succeeds, the new login is saved to your Secrets, locked to that site.

Terminal
curl https://browsa.io/v1/tasks \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Create an account on console.example.com with a new email address.",
    "llm": "browsa"
  }'
  • Name. From the host (console.example.com becomes EXAMPLE_CONSOLE), or as the task says: "save it as secret CONSOLE_BOT".
  • Result. The answer says "saved login as secret EXAMPLE_CONSOLE", and the result lists it:
result
"saved_secrets": [
  {"name": "EXAMPLE_CONSOLE", "id": "3e1a…", "type": "login",
   "origins": ["https://console.example.com"], "username_masked": "bo…"}
]
  • Opt out. "save_secrets": false on the task.
  • Permission. Saving changes your Secrets, so a scoped API key needs secrets:write.
  • Reuse. Attach it by name in the next task, like any other login.

What is protected

  • Typed only on its sites. Checked before the click that focuses the field and again before the keys. Elsewhere nothing is typed, the agent gets secret_origin_blocked and a blocked row goes to the usage log.
  • Passwords only into password fields. Never sent as raw keystrokes to whatever has focus.
  • Fenced after typing. Once a secret is typed, the browser may navigate, click and type only on the typed secrets' sites (and the task's allowed_domains). Anything else is refused: SECRET_TAINT_BLOCKED, logged as taint_blocked.
  • No scripts. A run with secrets has no evaluate action.
  • Masked. Values, codes and their base64, hex and reversed forms become <secret>NAME</secret> in steps, the answer, errors, logs, events and output files. Recordings keep tokens.
  • Screenshots. Step screenshots are off for a task with secrets. The model's own screenshots go off once a value is typed into a visible field.
  • Sealed at rest. Bound to the workspace, the secret and the field. No call returns a value.

Limits of the fence. A page on an allowed site receives the value, as it would from you: keep sites narrow. A value typed into an ordinary text field shows in the live view. Anyone who can run tasks in the workspace can have a secret typed on its sites. Raw CDP access to a browser is not fenced. A secret for any site (["*"] with allow_any_origin: true) has no fence at all.

Who can change secrets

Use
Any member and any API key of the workspace.
Dashboard
Create, edit, import, delete: owner or admin. Members get 403 SECRET_ROLE_REQUIRED.
API keys
A scoped key needs secrets:write, or gets 403 KEY_SCOPE_REQUIRED. Keys without scopes still work for now, with an X-Browsa-Warning header.
Terminal
curl https://browsa.io/v1/keys \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci", "scopes": ["secrets:write"]}'

Usage log

Every typing, code and refusal is logged with the site (no path) and the run. Kept after the secret is deleted. In the dashboard: Usage on the secret.

Terminal
curl "https://browsa.io/v1/secrets/GITHUB_LOGIN/usage?limit=100" \
  -H "X-API-Key: $BROWSA_API_KEY"
200
{"secret_id": "7b0c2f4e-…", "name": "GITHUB_LOGIN", "limit": 100, "next_cursor": null,
 "usage": [{"job_id": "…", "origin": "https://github.com", "action": "typed",
            "source": "task", "at": "2026-11-19T10:05:00Z"}]}
action
typed, totp, blocked (wrong site, nothing typed), taint_blocked (the fence stopped a step)
source
task, replay (a recipe or robot run) or session (act)
Paging
?limit= up to 500. Pass next_cursor as ?cursor= for older rows.

GET /v1/secrets and GET /v1/secrets/{id} add used_by: the robots and schedules that attach the secret.

Limits and errors

Name
A-Z, 0-9, _, up to 64. Unique. Fixed after create, like the type.
Per workspace
500 secrets
Per task, robot
20
Sites
1 to 10 per secret
Value
3 to 4096 characters, one line. Password up to 1024.
Description
Up to 500 characters
Import
100 secrets, 64 KiB of .env
Change, delete
PATCH or DELETE /v1/secrets/{id or NAME}. A secret in use answers 409 SECRET_IN_USE with used_by; add ?force=1 to delete anyway.
CodeStatusWhen
BAD_REQUEST400A field is missing or wrong, a site is not accepted, or a field is unknown
TOTP_CODE_MISMATCH400
totp_code is not the seed's current code
KEYPAIR_UNKNOWN400The keypair is unknown or expired: fetch it again
SEALED_VALUE_INVALID400A sealed field does not open with that keypair
SECRET_NOT_ATTACHED400The text or recipe names a secret the run did not attach
SECRET_NOT_FOUND400, 404No secret with that name or id
SECRET_NO_ORIGINS400, 409The secret has no sites yet: set them first
SECRET_REF_INVALID400
An act reference is not NAME, NAME:username, NAME:password or TOTP:NAME
SECRET_ROLE_REQUIRED403A dashboard member tried to change a secret
KEY_SCOPE_REQUIRED403
A scoped key without secrets:write
SECRET_TAINT_BLOCKED403After typing, an action left the secret's sites
SECRET_NAME_TAKEN409The name exists
SECRET_LIMIT409500 secrets already
SECRET_TYPE_MISMATCH409An import overwrite across types
SECRET_IN_USE409Delete of a secret a robot or schedule uses
BODY_TOO_LARGE413Over 512 KiB
SECRETS_UNAVAILABLE503Secrets are off on this server

A run that cannot open an attached secret fails SECRET_MISSING, or SECRET_NO_ORIGINS, before a browser opens. Nothing is charged. Messages name fields and secrets, never values.

Questions

Can the model read my password?

Not from a password field. The model is given the secret's name, and the value is typed at the keystroke. A value typed into an ordinary text field is on the page, so Browsa turns the model's screenshots off for the rest of the run, gives it no script action and keeps the browser on the secret's sites.

What happened to saved credentials?

Every saved credential is now a login secret with the same id. /v1/credentials and credential_ids keep working, so nothing breaks. New code should use /v1/secrets and secret_ids.

Do I still need the inline secrets field on a task?

Only for a value you want to use once without saving it (one-off secrets). Saved secrets work in schedules, robots and recipe runs, can carry a 2FA seed, and have a usage log.

Can a secret be used on any site?

Yes, with "origins": ["*"] and "allow_any_origin": true. It is not recommended: any page that tricks the agent can then receive the value, and such a secret has no site fence after it is typed.

Next steps

Save your first secret.

100 free credits. No card, no subscription.