Workspace policies

Policies control which requests a workspace accepts, which models and credentials can serve them, and when a fallback can run. Each policy has a target and one or more rules. A rule combines a request match with an action.

How policies apply

Every matching restriction must pass
Rules within a policy are unordered
All matching policies compose
Policies are traversed by ID for deterministic evaluation
The first matching fallback policy in that order supplies the fallback plan
Exact duplicate rules are invalid
Editing one policy cannot change another policy

Routing changes take effect after gateways adopt the updated workspace bundle. Budget state refreshes separately. See the budget tutorial for spending and status checks.

Configure a policy

Choose a target

Workspace

Apply the policy to all current and future inference keys and playground sessions in the workspace:

{"kind": "workspace"}

User

Target a human user or service account to apply the policy to all inference keys associated with them, current and future:

{
  "kind": "selected_users",
  "user_ids": ["01990aa3-4b4c-7000-8000-000000000001"]
}

Inference keys

Target specific keys. Keys created later are not included:

{
  "kind": "selected_keys",
  "key_ids": ["key-id-1", "key-id-2"]
}

Choose requests to match

Match all requests:

{"kind": "all_requests"}

Or combine model, stream, and capability criteria. Every supplied criterion must match:

{
  "kind": "request",
  "models": ["openai/gpt-4o-mini"],
  "stream": true,
  "capabilities": ["tools"]
}

Capabilities are tools, reasoning, and structured_output. Matching uses the original request, including when a fallback model handles it.

Choose actions

Add one action to each rule. A policy can contain multiple rules, and matching restrictions from all policies apply.

Allowed models

Limit matching requests and fallbacks to the listed catalog models:

{"kind": "models", "names": ["openai/gpt-4o-mini", "anthropic/claude-sonnet-4-6"]}

Allowed providers

Limit primary and fallback routes to the listed providers:

{"kind": "providers", "names": ["openai", "anthropic"]}

Credential access

Allow credentials from the listed scopes. Matching credential rules intersect. airmux chooses the most specific populated allowed scope in workspace, organization, instance order:

{"kind": "credential_access", "scopes": ["workspace", "org"]}

Strict parameter support

Reject a route if airmux would otherwise remove an unsupported caller-supplied parameter:

{"kind": "strict_parameters"}

Capability and input-modality checks always run.

Model price limit

Set maximum catalog prices in USD per million tokens. Both input and output prices must meet the limits:

{
  "kind": "price_limit",
  "max_input_price_per_mtok": "2.50",
  "max_output_price_per_mtok": "10.00"
}

This limits route prices, not the total request cost.

Request limits

Reject a request that explicitly asks for more output tokens than the limit. If it omits the limit, airmux does not invent one:

{"kind": "request_limits", "max_output_tokens": 4096}

Budget

Limit matching usage to a USD amount per UTC calendar day or month. Use shared to combine spend across the target or per_key to track each inference key separately:

{"kind": "budget", "amount_usd": "20.00", "period": "month", "aggregation": "shared"}

See the budget tutorial to create a budget and inspect spend.

Deny requests

Reject matching requests with 403 policy_denied and the configured message:

{"kind": "deny", "message": "Reasoning models are not approved for this workspace"}

Model fallbacks

Try backup models for rate limits, upstream errors, or timeouts:

{
  "kind": "fallback",
  "models": ["anthropic/claude-sonnet-4-6", "openai/gpt-4o-mini"],
  "on": ["rate_limited", "upstream_unavailable", "timeout"],
  "max_attempts": 3,
  "timeout_ms": 30000
}

A policy may contain one fallback rule with up to four backup models. max_attempts is 2–5 and includes the primary call. timeout_ms is 100–120,000. Invalid requests, policy denials, and authentication failures do not trigger model fallback. An upstream authentication failure may try another credential in the selected scope.

Create a policy

Use either the CLI or the management API. This example creates a workspace-wide output limit. The CLI uses your active organization and workspace context; the API path names both explicitly. Save this as policy.json:

{
  "name": "Production output limit",
  "enabled": true,
  "definition": {
    "target": {"kind": "workspace"},
    "rules": [
      {
        "match": {"kind": "all_requests"},
        "action": {"kind": "request_limits", "max_output_tokens": 1024}
      }
    ]
  }
}

CLI
cURL

airmux policies create policy.json --workspace production -f json

Set AIRMUX_URL, AIRMUX_ORG_ID, and a management key with policies.manage for the workspace, then create the policy:

curl --fail-with-body "$AIRMUX_URL/api/v1/organizations/$AIRMUX_ORG_ID/workspaces/production/policies" \
  -H "Authorization: Bearer $AIRMUX_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @policy.json

The response wraps the policy in {"data": ...}. The webapp can also create and edit policies with the same target, match, and action options.

Get started

Use the platform

Deploy and operate

Concepts

Contributing

Workspace policies

How policies apply

Configure a policy

Choose a target

Workspace

User

Inference keys

Choose requests to match

Choose actions

Allowed models

Allowed providers

Credential access

Strict parameter support

Model price limit

Request limits

Budget

Deny requests

Model fallbacks

Create a policy

​How policies apply

​Configure a policy

​Choose a target

​Workspace

​User

​Inference keys

​Choose requests to match

​Choose actions

​Allowed models

​Allowed providers

​Credential access

​Strict parameter support

​Model price limit

​Request limits

​Budget

​Deny requests

​Model fallbacks

​Create a policy

How policies apply

Configure a policy

Choose a target

Workspace

User

Inference keys

Choose requests to match

Choose actions

Allowed models

Allowed providers

Credential access

Strict parameter support

Model price limit

Request limits

Budget

Deny requests

Model fallbacks

Create a policy