Usage Policy

Control what your workspaces' agents and members can use.

---

What it governs

A usage policy decides which outside resources a workspace may consume, per category:

A workspace's own work is never blocked. The policy draws the line at the workspace boundary, not inside it.

---

Reach

Each category gets a reach, a ladder of how far outside the workspace its usage may go:

On top of the reach, the allowed list opens specific exceptions below it and the blocked list closes specific ones above it. Entries pin a specific resource or a publisher (every resource from that workspace). They are stored by identity, not by name, so renames and namespace changes can't dodge them.

Enforced reach (organization or workspace policy only) locks the reach for a category so member workspaces cannot widen it. They may still narrow it — a stricter reach or blocked entries — but they cannot set a wider reach or add allowed exceptions that would undo the org floor. The organization's own allowed list still applies on top of an enforced org reach. In the API this is reach_enforced on PolicyLayerDTO alongside reach.

---

In the settings editor

Open settings → organization → usage policy or settings → workspace → usage policy. The editor is split by category — apps, knowledge, agents, flows, and connectors — using tabs at the top. A dot on a tab means that category is restricted (anything other than everything it can see, or any allow/block exception).

For each category, the page walks through the decision in this order:

1. Whose … can be used — pick the reach (see the table above). When the workspace belongs to an organization, this organization is always one of the choices (you do not have to select it first to see it). Under the choice, up to three example resources show whether they would be usable or not usable with the current setting:

   • one from this workspace (your-workspace/…)
   • one from the organization (org-slug/…, only when the workspace belongs to an org)
   • one from anyone else (otherco/…, outside the org or the open grid)

   The workspace and organization slugs in those refs are real; the resource name after the slash (for example invoice-ocr) is an illustration, not your catalog. On the organization policy page, this workspace in the examples is a member workspace (the one you are in, or another workspace in the org). Change the reach and the examples update immediately, including while you have unsaved edits. The three rows only reflect the reach you picked — not allowed / blocked exceptions or enforcement from a higher layer.

   Server evaluation (the same logic as real usage) runs when you search in the allowed or blocked pickers and when you call POST /teams/{id}/rules/access with a draft of unsaved edits. The draft replaces only the layer you are editing inside the full policy ladder; organization enforced reach and rules still apply. When another layer decided the outcome, each row names it after the reason (for example outside the default by Acme (enforced)). If that decision is enforced, this layer cannot loosen it — not with a wider reach, not with an allowed exception, and not with a one-click allow on that row.

   When the reach is anything other than everything it can see, the organization policy page shows enforce for every workspace. Turn it on to save that reach as enforced (reach_enforced in the API): member workspaces may narrow the category further but cannot widen it. On a workspace policy page, the same control appears only when the organization (or a higher layer) has already enforced that category's reach — then you see that the floor is locked, not a second enforce toggle.

2. Allowed — resources or publishers that stay usable even when they fall outside the reach you chose (choose what to allow). Opens a search dialog: type a name before anything is listed, then pick rows and press done to replace the list. Search matches resources and publishers among what the workspace can see. Each page of results is split into two groups with headings: matching resources for the category (for example apps), then publishers (every resource from that workspace, now and later). Use load more when there are additional matches. Checked items stay selected if you search again until you press done.

3. Blocked — same picker as allowed, for resources or publishers that stay blocked even when they would fall inside the reach (choose what to block).

4. Blocked attempts — recent refusals for this category (see below). Visible to people who can edit the policy.

On the agents tab only, below whose agents can be used, what agents can do sets rules for every chat, agent, and machine in the organization or workspace — including coding agents on your machines. Individual chats and agents may add stricter rules; they cannot relax what an admin set here. A workspace allow wins over an organization ask first for people in that workspace.

Each rule is shown as a plain sentence (for example Block rm -rf … on machines tagged prod · enforced), with the engine syntax on a second line. Effects are allow, ask first, or block. Under more options, mode controls how the rule participates: default (lower admin layers can override), enforced (organization or workspace policy only — member workspaces cannot override), evaluate only (logs what would have happened; see blocked attempts), or disabled (kept but ignored).

The composer writes rule syntax for you:

• Shell commands — an exact command or anything starting with this (git push vs git push:*).
• Files and folders — a path, optionally and everything inside (~/secrets/**).
• Websites — a hostname or URL (stored as domain:…).
• Coding agent tools — a tool name with an optional pattern (Bash(git status:*), Edit).
• Type the rule — advanced entry for the raw specifier.

For shell commands, files and folders, and coding agent tools, narrow on which machines the rule applies: any machine, one machine, or machines tagged (for example prod). Websites and built-in agent tools apply everywhere; they do not take a machine selector.

Organization and workspace policies offer start from a template before you add rules: block destructive commands, ask before git push, block reading ~/.ssh and ~/.aws, and allow read-only commands. Pick a template to preview the sentences, then add one or many rules at once.

The server evaluates every real resource when someone tries to use it. The editor does not browse the full marketplace up front; reach examples, search-based exception pickers, and blocked attempts are where you shape and review policy.

Effective access (the paginated list backed by GET or POST /teams/{id}/rules/access) is the server's verdict on each resource the workspace can see. With an unsaved draft on POST, the API substitutes your in-progress reach and allow/block rules for the layer you are editing but still walks the full policy ladder (organization, workspace, member, and personal rungs). Each row includes decided_by (which layer's reach or rule decided) and enforced when that outcome cannot be loosened from the layer you are editing. UIs that offer one-click allow from such a list omit it when another layer's enforced rule or reach blocked the resource — adding an allow on this page would not lift that block.

---

Who sets it

• Organization policy: set by org admins under settings → organization → usage policy. It governs every workspace in the org, including the organization's own workspace. In the web app, member workspaces follow it and have no policy of their own. Through the API, org admins can give a member workspace its own layer; that layer is more specific and may loosen the org's, except for categories whose reach the org enforces and rules the org marks enforced.
• Workspace policy: for standalone workspaces only, set under settings → workspace → usage policy by people who can manage the workspace's policy. Others with access can open the same page read-only.
• Member policy (API): workspace or org admins with manage_policy can set a per-member layer with /teams/{id}/members/{userId}/rules. It applies only to that person in the workspace (or org) that wrote it. It stacks with the member's own permission rules (/me/rules), which only narrow access.

When the org governs a workspace's policy, settings → workspace → usage policy does not show a second copy of the rules. It shows only a notice that the organization sets the policy, with a link to settings → organization → usage policy when you may open it. View and change the policy in that one place. Anyone who belongs to a workspace in the organization can open settings → organization → usage policy read-only; editing it takes manage_policy on the organization workspace (org admins).

---

When something is blocked

The person hits a clear refusal naming the policy, and the attempt lands in the policy editor's blocked attempts feed — grouped by resource, most-hit first. An admin can allow any entry from the feed in one click, so real demand surfaces exactly where the decision is made.

Rules in evaluate mode never block by themselves; when one would have denied usage, the feed still records the would-be refusal so you can tune the rule before switching it to default or enforced.

On the API, blocked usage returns 403 with error code blocked_by_usage_policy and a detail message naming the policy. That is distinct from a generic forbidden (missing permission) or team_role_required (need a workspace admin). Integrations should treat it as "ask an org or workspace admin to allow this resource," not as a missing resource.

Blocked runs fail immediately: an agent message is marked failed instead of queued, a flow step fails its task instead of staying queued, and MCP tool calls return the block at record time.

---

Enforcement

The policy is judged for the calling workspace — the team on the API key or session — not the publisher of an agent or flow you invoke. A published agent may reach its own publisher's resources when it runs, but that does not bypass your workspace's usage policy for outside apps, agents, flows, MCP servers, or knowledge.

The API enforces the policy whenever a run is recorded: app tasks, agent runs (including continued chats, sub-agents, embed, and automations), flow runs, MCP tool calls, and knowledge or skill content access. There is no client-side path around it, and denials are written to the audit log.

For paid runs (such as starting an app task), the API checks usage policy before balance. A blocked resource returns 403 with blocked_by_usage_policy even when the workspace has no credits; the paywall (payment_required) only applies after the policy allows the run. See Tasks API — Run Task errors and Billing — Insufficient balance.

---

REST API

Integrations manage the same layer through the rules API:

The response is a PolicyLayerDTO: reach per usage kind (App, Agent, Knowledge, Mcp, Flow) plus rules. Usage-kind rules use allow or deny on apps, agents, knowledge, MCPs, and flows. Agent-action rules (the what agents can do section in the agents tab) use allow, ask, or deny on commands, paths, websites, and tools. Each rule includes enforcement (how it participates — see the API reference). For usage kinds, write targets with ref (publisher/name, publisher/*, MCP slug); the server resolves each ref once at write time and stores stable specifier values (a resource id or publisher:<team id> for a whole publisher). Each usage rule's label is the ref you wrote, for example bytedance/seedance.

Full request fields, capabilities, and pagination are in the Usage policy API reference. The older /usage-policy paths are removed in favor of these routes.