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.
| Type | Holds | For |
|---|---|---|
login | Username, password, optional 2FA seed | Signing in |
totp | A 2FA seed (base32 or otpauth://) | One-time codes on their own |
value | One line, 3 to 4096 characters | API keys, PINs, account numbers |
Allowed sites (origins) are required, up to 10. Always https.
| You write | Typed on |
|---|---|
example.com | example.com and every subdomain |
app.example.com | That host only |
https://app.example.com | That host only |
*.example.com | example.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"
}'import os
import requests
r = requests.post(
"https://browsa.io/v1/secrets",
headers={"X-API-Key": os.environ["BROWSA_API_KEY"]},
json={
"name": "GITHUB_LOGIN",
"type": "login",
"origins": ["github.com"],
"description": "Bot account for the release checks",
"username": "release-bot",
"password": os.environ["GITHUB_BOT_PASSWORD"],
},
)
r.raise_for_status()
print(r.json()["placeholders"])const r = await fetch("https://browsa.io/v1/secrets", {
method: "POST",
headers: { "X-API-Key": process.env.BROWSA_API_KEY!, "Content-Type": "application/json" },
body: JSON.stringify({
name: "GITHUB_LOGIN",
type: "login",
origins: ["github.com"],
description: "Bot account for the release checks",
username: "release-bot",
password: process.env.GITHUB_BOT_PASSWORD,
}),
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).placeholders);The answer is the secret without its values:
{
"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.
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_prefixplus the field name:username,password,totp_secret,valueorenv. - 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()// npm install @hpke/core
import { CipherSuite, DhkemX25519HkdfSha256, HkdfSha256, Aes256Gcm } from "@hpke/core";
const API = "https://browsa.io/v1";
const H = { "X-API-Key": process.env.BROWSA_API_KEY!, "Content-Type": "application/json" };
const kp = await (await fetch(`${API}/secrets/keypair`, { headers: H })).json();
const suite = new CipherSuite({ kem: new DhkemX25519HkdfSha256(), kdf: new HkdfSha256(), aead: new Aes256Gcm() });
const pk = await suite.kem.deserializePublicKey(Uint8Array.from(Buffer.from(kp.public_key, "base64")).buffer);
async function seal(field: string, value: string): Promise<string> {
const { enc, ct } = await suite.seal(
{ recipientPublicKey: pk, info: new TextEncoder().encode(kp.info_prefix + field).buffer },
new TextEncoder().encode(value),
);
return Buffer.concat([Buffer.from(enc), Buffer.from(ct)]).toString("base64");
}
const r = await fetch(`${API}/secrets`, {
method: "POST",
headers: H,
body: JSON.stringify({
name: "GITHUB_LOGIN",
type: "login",
origins: ["github.com"],
sealed_username: await seal("username", "release-bot"),
sealed_password: await seal("password", process.env.GITHUB_BOT_PASSWORD!),
keypair_id: kp.id,
}),
});
if (!r.ok) throw new Error(await r.text());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"]
}'import os
from browsa import Client
c = Client(api_key=os.environ["BROWSA_API_KEY"])
job = c.run_task(
task="Sign in to github.com with {{secret:GITHUB_LOGIN}} and list my open pull requests.",
llm="browsa",
secret_ids=["GITHUB_LOGIN"], # sent as is
)
print(job.final_result)
print(job.raw.get("secrets_used")) # names, types, sites; never valuesimport { Client } from "browsa";
const c = new Client({ apiKey: process.env.BROWSA_API_KEY! });
const job = await c.runTask({
task: "Sign in to github.com with {{secret:GITHUB_LOGIN}} and list my open pull requests.",
llm: "browsa",
secretIds: ["GITHUB_LOGIN"], // sent as secret_ids
});
console.log(job.finalResult);
console.log(job.raw.secrets_used); // names, types, sites; never valuesThe 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 text | Types |
|---|---|
{{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_idsis400 SECRET_NOT_ATTACHED. - Unknown.
{{secret:NAME}}for a name the workspace does not have is400 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 text | Same as |
|---|---|
secrets.NAME | {{secret:NAME}} |
secrets.NAME.username | {{secret:NAME:username}} |
secrets.NAME.password | {{secret:NAME:password}} |
secrets.NAME.totp | {{totp:NAME}} |
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.
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 withTOTP_CODE_MISMATCHand nothing is saved. - Options.
digits6 to 8,algorithmSHA1, SHA256 or SHA512,period15 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"]}}'robot = c.robots.get("ROBOT_ID")
c.robots.update(robot.id, settings={**robot.settings, "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"]
}'c.create_schedule(
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"],
)await c.createSchedule({
name: "Nightly sign-in check",
intervalSeconds: 86400,
task: "Sign in to github.com with {{secret:GITHUB_LOGIN}} and report the notification count.",
llm: "browsa",
secretIds: ["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):
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.
actwithsecret- Types a secret into one field, in place of
text.
{"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.
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.combecomesEXAMPLE_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:
"saved_secrets": [
{"name": "EXAMPLE_CONSOLE", "id": "3e1a…", "type": "login",
"origins": ["https://console.example.com"], "username_masked": "bo…"}
]- Opt out.
"save_secrets": falseon 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_blockedand ablockedrow 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 astaint_blocked. - No scripts. A run with secrets has no
evaluateaction. - 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 gets403 KEY_SCOPE_REQUIRED. Keys without scopes still work for now, with anX-Browsa-Warningheader.
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.
curl "https://browsa.io/v1/secrets/GITHUB_LOGIN/usage?limit=100" \
-H "X-API-Key: $BROWSA_API_KEY"{"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"}]}actiontyped,totp,blocked(wrong site, nothing typed),taint_blocked(the fence stopped a step)sourcetask,replay(a recipe or robot run) orsession(act)- Paging
?limit=up to 500. Passnext_cursoras?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
PATCHorDELETE /v1/secrets/{id or NAME}. A secret in use answers409 SECRET_IN_USEwithused_by; add?force=1to delete anyway.
| Code | Status | When |
|---|---|---|
BAD_REQUEST | 400 | A field is missing or wrong, a site is not accepted, or a field is unknown |
TOTP_CODE_MISMATCH | 400 | totp_code is not the seed's current code |
KEYPAIR_UNKNOWN | 400 | The keypair is unknown or expired: fetch it again |
SEALED_VALUE_INVALID | 400 | A sealed field does not open with that keypair |
SECRET_NOT_ATTACHED | 400 | The text or recipe names a secret the run did not attach |
SECRET_NOT_FOUND | 400, 404 | No secret with that name or id |
SECRET_NO_ORIGINS | 400, 409 | The secret has no sites yet: set them first |
SECRET_REF_INVALID | 400 | An act reference is not NAME, NAME:username, NAME:password or TOTP:NAME |
SECRET_ROLE_REQUIRED | 403 | A dashboard member tried to change a secret |
KEY_SCOPE_REQUIRED | 403 | A scoped key without secrets:write |
SECRET_TAINT_BLOCKED | 403 | After typing, an action left the secret's sites |
SECRET_NAME_TAKEN | 409 | The name exists |
SECRET_LIMIT | 409 | 500 secrets already |
SECRET_TYPE_MISMATCH | 409 | An import overwrite across types |
SECRET_IN_USE | 409 | Delete of a secret a robot or schedule uses |
BODY_TOO_LARGE | 413 | Over 512 KiB |
SECRETS_UNAVAILABLE | 503 | Secrets 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.