# Usage Policy > Control what your workspaces' agents and members can use. **URL:** https://inference.sh/docs/org/usage-policy **Last updated:** 2026-10-11 --- 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: | Category | Covers | |----------|--------| | **apps** | Running apps published by other workspaces or the public grid | | **knowledge** | Reading knowledge and skills published outside the workspace | | **connectors** (MCPs in the API) | Connecting to and calling MCP servers | | **agents** | Chatting with and invoking agents | | **flows** | Running flows | 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: | Reach | In settings | Meaning | |-------|-------------|---------| | **public** | **everything it can see** | Anything visible: the open grid, public publishers | | **organization** | **this organization** | Only resources from workspaces in the same organization | | **workspace** (`team` in the API) | **this workspace only** (on the org policy: **each workspace’s own**) | Only the workspace's own resources | 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`](/docs/api/rest/usage-policy#model) 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`](/docs/api/rest/usage-policy#effective-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). | In settings | What it protects | API `kind` | |-------------|------------------|------------| | **shell commands** | Commands an agent runs on a machine | `RemoteExec` | | **files and folders** | Paths agents may read or write | `Workspace` | | **websites** | Hosts agents may call over HTTP | `WebFetch` | | **coding agent tools** | Tools in Claude Code, Codex, and other harnesses | `Harness` | | **built-in agent tools** | inference.sh tools such as web search or running an app | `Tool` | 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`](/docs/api/rest/usage-policy#effective-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](/docs/api/rest/usage-policy#how-layers-combine), 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`](/docs/api/rest/usage-policy#member-policy). 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](/docs/api/rest/tasks#errors) and [Billing — Insufficient balance](/docs/api/rest/billing#insufficient-balance). --- ## REST API Integrations manage the same layer through the rules API: | Action | Endpoint | |--------|----------| | Read policy | `GET /teams/{id}/rules` or `GET /orgs/{id}/rules` | | Replace reach and usage-kind rules | `PUT /teams/{id}/rules` or `PUT /orgs/{id}/rules` | | Add one agent-action rule (`RemoteExec`, `Workspace`, `WebFetch`, `Harness`, `Tool`) | `POST /teams/{id}/rules` or `POST /orgs/{id}/rules` | | Change rule mode (`default`, `enforced`, `evaluate`, `disabled`) | `PUT .../rules/{ruleId}` | | Remove one rule | `DELETE .../rules/{ruleId}` | | Clear | `DELETE` on the same paths | | Blocked attempts | `GET .../rules/denials` | | Preview/search resources | `GET` or `POST /teams/{id}/rules/access` | 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:` 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](/docs/api/rest/usage-policy) reference. The older `/usage-policy` paths are removed in favor of these routes.