Skip to main content

Security

Who can see and change what, which credential to use where, and how your data is stored.

Dashboard roles​

Access follows organization membership. A member reads, an admin or owner writes. Removing or demoting someone takes effect on their next request, and their broods login stops working.

Nobody joins an organization without saying yes. Someone with members:write invites an email under Organization settings, Members; no email is sent, so tell the person. The invitation shows as Pending invitations under the members table and gives no access of any kind until it is accepted. An email that has never signed in to Broods can be invited too: the invitation waits on that address and appears once its owner signs in with it, verified. The invited person sees a line under the header on every page and accepts or declines it there, once their email is verified. Only the address an invitation went to accepts it: if the invited person's sign-in email changes, they can still decline but no longer accept, and an admin revokes it and invites the new address. An invitation and its seat go when its sender leaves, is removed or deletes their account; it lapses at accept when its sender can no longer grant its role. Revoke on a pending row withdraws it. Any member except the owner leaves from their own row in Members; the owner deletes the organization instead.

A custom role, made under Organization settings, Roles, sits on the member tier and adds what its policies allow: seeing or changing keys, changing members, changing access. A policy or a rule scoped to a project or a stage counts only there, and only an enforce-mode policy counts. A member grants no more than they hold: members:write cannot hand out the admin tier or a role with a permission the caller lacks, nor change or remove a member whose role holds one, and access:write can still attach any policy to any role, including one's own, so give it as you would admin. Policies and permissions are the organization's, under the tabs beside it, so one policy can serve a role, an agent or a key. Roles and policies are read with the same deny-wins order OPA uses for agents at run time.

OperationMemberAdmin, owner
Read agents, stages, canvas, files, logs, traces, usageyesyes
Test an agent in the dashboard chatyesyes
Create or edit agents, the canvas, workspace files, MCP serversnoyes
Reveal, set or delete an environment variablenoyes
Reveal or rotate the runtime keynoyes
Generate or rotate the user token signing secretnoyes
Turn an agent's user token requirement on or offnoyes
Create, clone or promote a stage. Create or delete a project.noyes
Manage agent webhooks and scheduled jobsnoyes
Exec, open a terminal, snapshot, suspend or terminate a sandboxnoyes
Call an MCP tool from the explorer. Create or revoke project keys and roles.noyes

The CLI only works for owners and admins.

Credentials​

These keys are yours to hold. Use the narrowest one that works.

KeyPrefixScopeWhat it can doNever
Account keybask_The whole accountEverything: create and change agents, crons, files and roles, run agentsPut it in a frontend or hand it to an agent
Scoped keybask_The account, or one project and stageRead or write what its permissions allow, until it expiresExpect it to manage keys or roles, assume a role, or sync with the CLI
Project keybpdk_One project and stageDeploy, set and list environment variables, rotate the signing secretExpect it to read a variable's value
Runtime keybsk_One project and stageRun agents with publicAccess: trueExpect it to read logs or change config
Signing secretbsig_One project and stageSign user tokens on your serverPut it in a frontend

BROODS_ACCOUNT_SECRET holds the account key, BROODS_TOKEN a project key, BROODS_API_KEY the runtime key, and BROODS_USER_TOKEN_SECRET the signing secret.

The rest are issued for you and expire or follow your membership:

CredentialPrefixUse it forNever
CLI loginbcli_Your own machineShare it
Role sessionbsts_Handing a tool or agent narrow API accessExpect it to outlive 12 hours
Stage session ticketbdts_Minted for you by the dashboard and broods logsStore it. It lasts 15 minutes.
Run tokenbrt_Sandbox code reading its agent's runsStart a run with it, or expect it past the run
User tokenbuat_Telling a run which of your users is callingMint it in a browser. It lasts 60 minutes at most.

Every Broods credential starts with b, so you and a secret scanner can tell it from another vendor's key.

The runtime key is the one key meant to sit in a frontend, so it is limited:

  • It only reaches agents with publicAccess: true in its own stage. Another stage's agent answers 404.
  • It cannot send system messages or model overrides unless the agent sets allowRunOverrides: true.
  • continue with it only reopens conversations the direct API started, never a channel conversation.
  • It cannot open logs, traces or the machine socket.
  • An agent that requires a user token refuses it without one. See below.

Users behind the runtime key​

Conversation keys are readable by anyone with the runtime key

The runtime key sits in your website's code, so every visitor has it. Without a user token, a request names its conversation with conversationKey and Broods takes it as given. A visitor who guesses another user's key (a user id, an email, ticket-42) can read that conversation's runs, steer it, answer its approvals and continue it. Send a user token on every runtime-key request, and turn the requirement on for every agent your frontend reaches.

Your backend knows who is signed in, so it vouches for them. It signs a short-lived user token with the stage's signing secret, and your frontend sends that token beside the runtime key.

// On your server, after your own sign-in check.
import { signUserToken } from "broods";

const userToken = await signUserToken({
userId: session.user.id,
ttlMs: 10 * 60 * 1000, // 10 minutes is the default, 60 the most
}); // reads BROODS_USER_TOKEN_SECRET
// In the browser.
import { BroodsClient } from "broods";

const client = new BroodsClient({
apiKey: "bsk_...",
userToken: () => fetch("/api/broods-token").then((r) => r.text()),
});
await client.run(api.agents.support, {
conversationKey: "ticket-42",
input: "Where is my order?",
});

With a valid token, every conversation key and event id of that request lives under that user. ticket-42 becomes bsu:<userId>:ticket-42, and responses name it that way. Another user's token, or no token, cannot reach it, for new runs, steering, approvals, continue or reading a run.

Token fieldWhat it does
userIdYour id for the user. Letters, digits and ._@+=-, at most 128 characters
conversationsOptional. The only conversation keys this user may use. Omit to allow any key under the user
credentialOptional. The user's own bearer for your hosted MCP servers. See below
ttlMsLifetime. Default 10 minutes, at most 60
  • broods dev and broods deploy write the signing secret to .env.local when the stage has none yet. They never rotate a secret the stage already has; they warn when your checkout does not hold it. You can also generate or rotate it on the dashboard's Runtime key tab. It is shown once. Rotating it voids every token it signed at once.
  • Every agent created from now on requires a user token with the runtime key. An agent made before keeps working without one until you turn the requirement on in its Details tab. Plan to turn it on for every existing agent your frontend reaches within 30 days; a token is honored even while the requirement is off, so send tokens first, then flip the switch.
  • A forged or expired token fails the whole request with 401. A missing one on an agent that requires it is 403 user_token_required. A conversation the token does not list is 403 user_token_conversation.
  • On the WebSocket, BroodsWebSocketClient takes userToken too. It rides the upgrade as a broods.user.<token> subprotocol entry. The gateway closes the socket with 4419 when the token expires; open a new one with a fresh token.
  • The account key and the dashboard's stage session ticket speak for the whole stage and take no user token.
  • Keys starting with bsu: are reserved for user namespaces.
  • The token's userId reaches your agent's remote and hosted MCP servers as the first link of X-Broods-Principal, so a tool can act for that user. A machine server gets no principal, and a turn that queued behind a running one arrives without it, so a tool must refuse when the header is missing. Broods verified the token, so the id is yours to trust, but check the server's own credential header too: anyone can send a header to a public URL.

Acting with the user's own credential​

When a tool must call another API as the user, put that user's credential in the token:

const token = await signUserToken({
userId: user.id,
credential: user.apiToken,
});
  • Every tool listing and call the run makes to one of your account's hosted MCP servers carries it as X-Broods-User-Credential. Remote URL servers, machine and sandbox servers never get it, and neither do bash, the model, logs or stored runs.
  • It lives only in memory for that request's run and the subagents it starts. A run resumed later (after an approval, a restart, or a turn that queued behind another) has none, so a tool must refuse when the header is missing.
  • At most 512 printable ASCII characters, no spaces. It is encrypted inside the token under the signing secret, so the browser holding the token cannot read it. The token is still a bearer until it expires, so keep the credential short-lived.
  • The name is reserved: a configured header of that name, in any case, is dropped.

The account key is shown once when your organization's API account is provisioned. Rotate it under Organization settings, API access; that takes keys:write for the organization, which admins hold and a role can be granted. The account key is the whole account API, so give organization-wide keys:write as you would admin. Rotation breaks everything holding the old one.

A scoped key is made on the same page with New key: a name, a scope (the whole organization, or one project and stage), an expiry (30 days, 90 days, 1 year or never) and a starting access, Read only or Full access. It is shown once and carries the bask_ prefix, but it acts like a role session that never needs re-assuming: its permissions are the role's policy and its scope is the role's pin. Its panel then sets no access, read, or read and write for each config area, and changes the scope and expiry in place; each change applies to the next request the key makes. Read and write on sandboxes lets the key run commands and open a terminal in them. Revoke stops it at once, and deleting a stage deletes the keys pinned to it. The audit log names each scoped key as accountApiKey, and the list shows when it was last used.

A project key is an API key created for one stage under Project settings, Keys, and shown once. That page asks keys:write per stage, so a grant on one stage rotates or revokes only that stage's keys; keys:write also sees the keys it may change. The list shows when each key was last used, to within an hour. See Deploying from CI.

Roles​

A role gives a tool or agent less than the full account key. You create a role with a policy over the config-plane API, then trade it for a short-lived session token, the way AWS STS works.

import { BroodsAccountClient } from "broods/account";

const owner = new BroodsAccountClient({
accountSecret: process.env.BROODS_ACCOUNT_SECRET,
});

const role = await owner.createRole({
name: "agents-reader",
policy: {
version: 1,
rules: [{ id: "r1", effect: "allow", actions: ["agents:read"] }],
},
});

const session = await owner.assumeRole(role.roleId, { ttlSeconds: 900 });
const scoped = new BroodsAccountClient({ sessionToken: session.token }); // can list and read agents, nothing else
  • Actions are <resource>:read and <resource>:write for account, agents, audit, channels, crons, env, hooks, mcp, policies, sandboxes, skills and workspaces.
  • resources.resourceIds limits a rule to specific ids, "*" for all. A deny beats an allow, and no matching allow means 403.
  • projectId and stageId pin a role to one stage. A pinned session reaches only agents, crons, channels, MCP servers, policies, sandboxes and workspaces on that stage. Lists, creates, and account-wide resources such as the account, audit, env, hooks and skills answer 403. A write that points one of its resources at another stage's, such as a production sandbox on a development agent or a cron moved to a production agent, answers 400. So does an agent or workspace write that names an account env var as ${NAME} the session may not read with env:read (a workspace's R2 keys are such names), which a pinned session never may, or that repoints an MCP server (its URL, transport, bundle or OAuth) whose agents send it such a name.
  • Sessions last 1 hour by default, 12 at most. Only a hash is stored, and the token is shown once.
  • The account key, a CLI login, or a runtime key can assume a role. A runtime key may only assume roles pinned to its own stage.
  • Sessions cannot mint sessions, rotate the account key, or manage roles.
  • PATCH the role with status: "disabled" to end every live session at once.
  • Opening the machine socket for a sandbox needs sandboxes:write on it.

For the CLI's MCP server, prefer a role session in BROODS_SESSION_TOKEN over the account key. See CLI reference.

How your data is stored​

  • Agent configs, including provider keys and channel tokens, are encrypted with AES-256-GCM before they are stored. API responses show secret fields as ********. Sending ******** back in an update keeps the stored value.
  • Environment variable values are encrypted and write-only for project keys. Webhook signing secrets are write-only in the dashboard.
  • The account key is stored as a hash only.
  • Workspace files, skills, and hook and MCP bundles are in private S3 buckets with public access blocked.
  • Deleting a project removes everything under it on every stage. Deleting the account removes all of its data. Neither can be undone.

Code you upload​

  • Code hooks run in an isolated V8 sandbox with no file system, no imports, and network only through a fetch that blocks private and metadata addresses.
  • Hosted MCP servers run outside the Broods core: in a Cloudflare Workers isolate per bundle, or a Lambda child process per bundle with nothing but log-writing permissions. The isolate or child is containment, not a trust boundary: accounts can share a warm runner environment until per-account isolation is switched on, so treat anything the server can reach as reachable by its code and keep secrets out of the bundle.
  • Sandbox commands start with a clean environment. Only the envVars you declare reach them. Workspace mounts use short-lived credentials limited to that workspace's own files.

Outbound URLs​

MCP server URLs, OAuth token URLs, webhook URLs and custom channel API URLs must be public https. Private, loopback, link-local and metadata addresses are refused when you save and again when used, and redirects are not followed.

Self-hosters and contributors can read Security internals for the details.