Policies & approvals

Govern models, spend, tokens, rates, tools and data capture with policies, roll them out in monitor mode, and keep people in the loop with approvals.

On this page

Policies decide what your AI workloads may do: which models they use, how much they spend, how many tokens and requests they send, which tools they call, and what needs a human’s approval. Manage them in Governance → Policies. Every change creates a revision and an audit event, and reaches the gateway within seconds.

How a policy is built#

How a policy is built
Field	Values
Type	One of the types below, each with its own typed rules
Scope	The organization, a workspace, an environment, an agent, a workflow or a team
Enforcement	`monitor` records violations without blocking; `enforce` blocks or requires approval
Status	`active`, `disabled` or `draft`
Priority	Lower numbers are evaluated first (default 100)

A policy applies to a request when it is active and its scope matches the request: the organization, workspace and environment come from the API key, and the agent, workflow and team come from the X-AIW-* headers or the SDK context.

Policy types#

Policy types
Type	Rules (example)	On violation (enforce)
`model_allowlist`	`{"models": ["gpt-5", "gpt-5-mini"]}`	`403 model_not_allowed`
`model_denylist`	`{"models": ["gpt-4.1"]}`	`403 model_not_allowed`
`spend_limit`	`{"period": "day", "limit_usd": 25, "alert_thresholds": [0.5, 0.8, 1.0]}`	`402 budget_exceeded` once spend reaches the limit; a notification at each threshold and an incident at 100%
`token_limit`	`{"max_tokens_per_request": 120000, "max_tokens_per_day": 5000000}`	`403 token_limit_exceeded`
`rate_limit`	`{"requests_per_minute": 600}`	`429 rate_limited` with `Retry-After`
`action_approval`	`{"models": ["gpt-4.1"], "environments": ["production"]}`	`403 approval_required` until the request carries an approved `X-AIW-Approval-Id`
`tool_allowlist`	`{"tools": ["search_kb", "lookup_order"]}`	`403 tool_not_allowed` at the gateway; `ToolNotAllowedError` in the SDKs; `-32001` in the MCP gateway
`tool_approval`	`{"tools": ["issue_refund"], "min_risk": "high"}`	The SDK or MCP gateway requests an approval before the tool runs
`data_capture`	`{"mode": "metadata_only"}`	Capture is downgraded to the most restrictive mode
`end_user_quota`	See end‑user plans	`429 end_user_quota_exceeded` or `403 model_not_allowed`

Every block by the gateway is recorded as a span with status=blocked, and the policy-violation detector turns violations into rows on the policy page and, in enforce mode, into incidents.

Roll out safely#

Create the policy in monitor mode, or as a draft.
Simulate it against your recent traffic: the policy form shows how many requests matched and how many it would have blocked, with a sample of affected requests.
Watch Violations on the policy page for a few days.
Switch to enforce. The revision history keeps every earlier version.
Tell application owners which error codes to handle. See gateway errors.

Create policies from code with the REST API, for example with a personal access token:

Terminal

curl -s https://worksi.ai/api/v1/policies \  -H "Authorization: Bearer aiw_pat_…" \  -H "Content-Type: application/json" \  -d '{"name": "Production models", "type": "model_allowlist", "scope_type": "org",       "rules": {"models": ["gpt-5", "gpt-5-mini"]}, "enforcement": "monitor"}'

Tool policies#

A tool is disallowed when an applicable tool_allowlist policy does not list it, or when the agent’s registered allowed tools are set and do not include it. A tool requires approval when an applicable tool_approval policy lists it (or the tool’s risk level reaches the policy’s min_risk), or when the registered tool is marked as requiring approval.

Tool policies
Where	Enforce	Monitor
Gateway	A request that declares a disallowed tool gets `403 tool_not_allowed`	Allowed; the span is flagged
SDKs (`aiw.tool()`)	Disallowed: the tool doesn’t run. Approval needed: requested before the tool runs.	Never blocks or asks
MCP gateway	`-32001` or `-32002` JSON‑RPC errors	Allowed; the call is flagged
Detection	Violations are recorded and open an incident	Violations are recorded only

Tool allowlists, tool approvals and model-access approvals (action_approval) are available on Pro, Business and Enterprise, and during the trial. Every other policy type is available on every plan.

Approvals#

Approvals
Type	Created by	What approval does
`ops_action`	A high-risk recovery action under four‑eyes	The action executes
`tool_call`	The SDKs, the MCP gateway or a person	The tool may run; it is covered for the rest of the run
`model_access`	An agent or a person	The gateway accepts `X-AIW-Approval-Id` for that model
`spend_increase`, `policy_exception`, `custom`	An agent or a person	A recorded decision for the requester to act on

Approvals move from pending to approved, rejected, cancelled or expired (after 24 hours by default). Deciding needs the approvals:decide permission (owners, admins and operators) and, for critical risk, an admin. Every request and decision is audited, appears on the linked incident’s timeline and can notify your alert channels.

Four‑eyes#

With four‑eyes enabled (Business and Enterprise), high-risk recovery actions such as pausing a production agent need a second person: nobody can approve their own request. Risk is computed on the server and fails closed; when the environment cannot be determined, the action is treated as production.

Questions? Email info@xeoo.io.