> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace policies

> Configure who a policy targets, which requests it matches, and the actions airmux applies.

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
* All matching policies compose
* Policies are traversed by ID for deterministic evaluation

## Create a workspace policy

This walkthrough creates a self-contained policy that caps every request in the active workspace at 1,024 output tokens, then verifies the behavior from the CLI.

<Steps>
  <Step title="Create the policy configuration">
    Save this as `output-limit-policy.json`:

    ```json theme={null}
    {
      "name": "Production output limit",
      "enabled": true,
      "definition": {
        "target": {"kind": "workspace"},
        "rules": [
          {
            "match": {"kind": "all_requests"},
            "action": {"kind": "request_limits", "max_output_tokens": 1024}
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Create and inspect the policy">
    The CLI uses your active organization and workspace context. Use `--workspace` to target a specific workspace:

    ```bash theme={null}
    airmux policies create output-limit-policy.json --workspace production -f json
    airmux policies list
    ```

    The webapp can also create and edit policies with the same target, match, and action options.
  </Step>

  <Step title="Verify behavior">
    With the policy active, a Chat Completions request with `max_completion_tokens` greater than `1024` returns `403 policy_denied`. A request that omits the field sends `1024` upstream and reports a `defaulted` adjustment with `source: policy`. If several matching policies set limits, the tightest ceiling applies.
  </Step>
</Steps>

## Configure a policy

### Choose a target

#### Workspace

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

```json theme={null}
{"kind": "workspace"}
```

#### User

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

```json theme={null}
{
  "kind": "selected_users",
  "user_ids": ["01990aa3-4b4c-7000-8000-000000000001"]
}
```

#### Inference keys

Target specific keys. Keys created later are not included:

```json theme={null}
{
  "kind": "selected_keys",
  "key_ids": ["key-id-1", "key-id-2"]
}
```

The webapp's **Applies to** selector exposes the same three targets, including service accounts in the user picker.

### Choose requests to match

Match all requests:

```json theme={null}
{"kind": "all_requests"}
```

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

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

### 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:

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

#### Allowed providers

Limit primary and fallback routes to the listed providers:

```json theme={null}
{"kind": "providers", "names": ["openai", "anthropic"]}
```

#### 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:

```json theme={null}
{"kind": "budget", "amount_usd": "20.00", "period": "month", "aggregation": "shared"}
```

See the [budget tutorial](/docs/guides/budgets) to create a budget and inspect spend.

#### 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:

```json theme={null}
{"kind": "credential_access", "scopes": ["workspace", "org"]}
```

#### Strict parameter support

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

```json theme={null}
{"kind": "strict_parameters"}
```

#### Model price limit

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

```json theme={null}
{
  "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:

```json theme={null}
{"kind": "request_limits", "max_output_tokens": 4096}
```

#### Deny requests

Reject matching requests with `403 policy_denied` and the configured message:

```json theme={null}
{"kind": "deny", "message": "Reasoning models are not approved for this workspace"}
```

#### Model fallbacks

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

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

Invalid requests, policy denials, and authentication failures do not trigger model fallback. An upstream authentication failure may try another credential in the selected scope.