# Policies

A Policy evaluates an Agent tool call in real time against conditions (Action type, User attributes, Connection attributes) and produces one outcome: Auto-approve, Require approval or Deny. Policies are the enforcement layer the MCP Gateway uses on every call.

***

### 📖 Key concepts

* **Policy**: A rule that produces one outcome (Auto-approve / Require approval / Deny) when its conditions match a tool call.
* **Default Policies**: Four Policies pre-loaded on every org, one per Action type. Cannot be deleted, reordered or deactivated. Outcome editable.
* **Custom Policies**: Admin-authored Policies that take priority over defaults. Status can be Active, Draft or Archived.
* **Action type**: The four classifications Policies operate on: **Read**, **Write**, **Destructive**, **External**. Derived from MCP tool annotations.
* **Outcome**: The decision a Policy produces. Three values used everywhere: Auto-approve (green), Require approval (yellow), Deny (red).
* **Conflict resolution**: When two active Policies match the same tool call, the engine resolves deterministically: Custom Policies outrank Default Policies, and within a tier the more restrictive outcome wins (Deny > Require approval > Auto-approve). Every tool call resolves to exactly one outcome.

:bulb: *Why this matters*: Defaults give you coverage on day one. Custom Policies tune that coverage to your company's risk model. The conflict rule means Policy stacks resolve deterministically: there is exactly one outcome per tool call.

***

### 📊 The Policies surface

**Navigation**: Settings → Policies.

Two tabs:

* **Custom Policies**: the default landing tab. Lists every Custom Policy you have authored.
* **Default Policies**: the four built-in cards.

***

### 🛠 Default Policies

#### Definition

Four cards, one per Action type, present from org creation.

| Action type     | Default outcome  |
| --------------- | ---------------- |
| **Read**        | Auto-approve     |
| **Write**       | Require approval |
| **Destructive** | Deny             |
| **External**    | Deny             |

Each card shows the Action type label, the outcome badge and a one-line description.

#### Capabilities

* **Outcome editable** via a right-side drawer.
* **Conditions fixed**: the Action type is the only condition; not editable.
* **Cannot be deleted, reordered or deactivated**. The Active toggle on each card is permanently on and greyed; hover surfaces "Default policies are system-defined and cannot be deactivated."
* **Always evaluated last**: Custom Policies take priority.
* **3-dot menu**: Edit outcome, Copy link.

#### How to edit a Default Policy

1. Open Settings → Policies → **Default Policies**.
2. Click the 3-dot menu on the card you want to change.
3. In the drawer, pick a new outcome (Auto-approve / Require approval / Deny).
4. Click **Save**. The change applies on the next gateway tool call evaluation. No retroactive effect on in-progress sessions.

***

### 🛠 Custom Policies

#### Definition

Admin-authored Policies that evaluate before defaults. Each Custom Policy has a status (Active / Draft / Archived) and an outcome.

#### List & filter

* **Navigation**: Settings → Policies → **Custom Policies**.
* **Search bar**: search by Policy name or keyword.
* **Filter panel** (icon next to search): filter by **Status** (Active / Draft / Archived) and **Outcome** (Auto-approve / Require approval / Deny). Both multi-select.

***

#### Create a Custom Policy

**Navigation**: Settings → Policies → **New** → choose **Generate with AI** or **Create manually**.

The Create flow is a full-page slide-over with two columns.

**Left panel: General info**:

* **Generate with AI toggle** (off by default).
* **Name** (required) and **Description** (optional). Editable in either path.

**Right panel: Conditions & outcome**:

* **If** block: the condition builder (Visual or Code).
* **Then** block: the outcome dropdown (Auto-approve / Require approval / Deny).

**Bottom bar**: Cancel | **Save as draft** | **Publish**.

* **Save as draft** closes the flow and shows a toast: "Policy successfully saved as draft." The Policy lands in the list as Draft.
* **Publish** makes the Policy live immediately and shows a toast: "Policy has been published."

**Manually**:

1. Toggle Generate with AI off.
2. Enter Name and (optional) Description.
3. Build conditions in the Visual builder.
4. Pick an outcome.
5. Click **Save as draft** or **Publish**.

**With AI**:

1. Toggle Generate with AI on. The left panel reveals the **Instruction** text area.
2. Type a natural-language instruction. Use `@` to surface available condition properties: Action type, App attributes (category, AI risk level) and User attributes (department, job title, location).
3. Click **Generate policy**. Name, Description, Conditions and Outcome auto-populate.
4. Edit any field freely, or click **Generate policy** again to regenerate (this overwrites Name, Description, Conditions and Outcome).
5. Click **Save as draft** or **Publish**.

***

#### Visual & Code authoring

* **Visual view**:
  * **If** block: condition rows, each with a property dropdown, operator, value(s) and a 3-dot menu (Duplicate, Delete). Group conditions with **And** / **Or**. Within a group: Add rule, Add subgroup. At top level: Add rule, Add group, Clear all.
  * **Then** block: the outcome dropdown.
* **Code view**: a read-only Rego view of the same conditions, generated from the Visual builder. Rego is the policy language of [OPA](https://www.openpolicyagent.org/); direct Rego authoring is on the roadmap.

***

#### Custom Policy detail

**Navigation**: Settings → Policies → Custom Policies → click any Policy card.

The detail page has two tabs in a left side menu:

* **General info**: status, description, created by, last updated (and by whom), and **Matching apps** (the catalog apps whose attributes match this Policy's conditions; open the group to list them). An **Activity** card below shows Triggered (30d), Last triggered and Sessions affected.
* **Conditions & outcome**: read-only view with a Visual / Code toggle. Use **Edit policy** in the 3-dot menu to open the full-page edit flow, pre-populated with current values.

{% hint style="info" %}
The Activity panel (Triggered, Last triggered, Sessions affected) renders placeholder data until the session activity ETL ships.
{% endhint %}

***

#### 3-dot menu actions

| Action            | When shown         | Effect                                                                                                                |
| ----------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Edit policy**   | Always             | Opens the full-page edit flow pre-populated with current values.                                                      |
| **Publish**       | Draft or Archived  | Sets the Policy to Active. The gateway evaluates it on the next tool call.                                            |
| **Move to draft** | Active or Archived | Returns the Policy to Draft. No longer evaluated until republished.                                                   |
| **Archive**       | Active or Draft    | Sets the Policy to Archived. No longer evaluated; history remains visible.                                            |
| **Duplicate**     | Always             | Opens the New Policy flow pre-filled from this Policy, named "\[name] (Copy)". Save as draft or publish to create it. |
| **Copy link**     | Always             | Copies the direct URL to the Policy detail page.                                                                      |

***

### 🔁 Conflict resolution

When two active Policies match the same tool call but produce different outcomes, the engine resolves deterministically.

1. **Custom > Default**: any Custom Policy outranks any Default Policy.
2. **Within a tier, more restrictive wins**: Deny > Require approval > Auto-approve.

Every tool call produces exactly one outcome. Nothing falls through. Specificity-based tiebreakers are on the roadmap.

***

### 📋 Policy statuses

| Status       | What it means                                                                              |
| ------------ | ------------------------------------------------------------------------------------------ |
| **Active**   | Live. Evaluated by the gateway on every matching tool call.                                |
| **Draft**    | Saved but not yet live. Not evaluated. Publish from the list, the detail page or the menu. |
| **Archived** | Retired. No longer evaluated. History remains visible.                                     |

***

### 🔗 Related pages

* [Users](/docs/ai-agent-access/how-to-guides/users.md)
* [All Connections](/docs/ai-agent-access/how-to-guides/connections/all-connections.md)
* [Agent Activity](/docs/ai-agent-access/how-to-guides/agents/agent-activity.md)
* [The Tool Call Lifecycle](/docs/ai-agent-access/concepts/the-tool-call-lifecycle.md)
* [The MCP Gateway](/docs/ai-agent-access/concepts/the-mcp-gateway.md)
* [Audit Log](/docs/ai-agent-access/concepts/audit-log.md)
* [Trust and Security](/docs/ai-agent-access/concepts/trust-and-security.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.cakewalk.security/docs/ai-agent-access/how-to-guides/policies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.