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

# Policies

> Configure organization-level rules to allow, gate, or block actions.

## Overview

Policies give your organization fine-grained control over which actions run, which require review, and which are blocked outright. They complement built-in high-risk connector checks and are managed through the authenticated dashboard REST API (`TEAM` plan required).

## API

All endpoints require operator dashboard authentication (`jwtAuth` with `TEAM` plan). Successful responses use this envelope:

```json theme={null}
{
  "data": { ... },
  "error": null,
  "timestamp": "2026-08-09T12:00:00.000Z"
}
```

A policy returned by the API has this shape:

```json theme={null}
{
  "id": "clx...",
  "organizationId": "org_...",
  "apiNamePattern": "stripe.refunds.*",
  "condition": {
    "field": "amount",
    "operator": "gt",
    "value": 10000
  },
  "action": "REQUIRE_APPROVAL",
  "enabled": true,
  "createdAt": "2026-08-09T12:00:00.000Z",
  "updatedAt": "2026-08-09T12:00:00.000Z"
}
```

### List policies

```http theme={null}
GET /policies

// 200
{ data: Policy[], error: null, timestamp: string }
```

### Create a policy

```http theme={null}
POST /policies
Content-Type: application/json

{
  "apiNamePattern": "stripe.refunds.*",
  "condition": {
    "field": "amount",
    "operator": "gt",
    "value": 10000
  },
  "action": "REQUIRE_APPROVAL",
  "enabled": true
}

// 201
{ data: Policy, error: null, timestamp: string }
```

`apiNamePattern` and `action` are required. `condition` is optional, and `enabled` defaults to `true`.

### Update a policy

```http theme={null}
PUT /policies/:id
Content-Type: application/json

{
  "apiNamePattern": "stripe.refunds.*",
  "action": "BLOCK",
  "enabled": true
}

// 200
{ data: Policy, error: null, timestamp: string }
```

### Toggle policy enabled status

```http theme={null}
PATCH /policies/:id/toggle

// 200
{ data: Policy, error: null, timestamp: string }
```

### Delete a policy

```http theme={null}
DELETE /policies/:id

// 200
{ data: { id: "clx...", deleted: true }, error: null, timestamp: string }
```

## API name matching

`apiNamePattern` supports exact names, wildcard suffixes, and a full wildcard:

| Pattern | Matches |
| - | - |
| `stripe.refunds.create` | Only `stripe.refunds.create` |
| `stripe.refunds.*` | Any action whose name starts with `stripe.refunds.` |
| `*` | Every action |

## Payload conditions

Add an optional `condition` to apply a policy only when a payload field matches.
Supported operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`.

```json theme={null}
{
  "apiNamePattern": "stripe.refunds.create",
  "condition": {
    "field": "amount",
    "operator": "gt",
    "value": 10000
  },
  "action": "BLOCK"
}
```

## Evaluation and approval behavior

When more than one enabled policy matches, the most restrictive result wins:
$\text{BLOCK} > \text{REQUIRE\_APPROVAL} > \text{ALLOW}$

### Enforcement Mechanism

* **`BLOCK`**: When logged to `POST /sessions/:id/actions`, records the action as `FAILED` upon logging and returns HTTP `403` with error type `policy-blocked`.
* **`REQUIRE_APPROVAL`**: When logged to `POST /sessions/:id/actions`, transitions the action to `PENDING_APPROVAL` with an after-execution approval request. If a reviewer approves, action becomes `SUCCESS`. If rejected, single-action rollback is executed.
* **`ALLOW`**: Permits the action to proceed normally.

<Warning>
  **Server Enforcement Boundary**: Server-side policy results are recorded and enforced as far as the SDK cooperates. An agent that bypasses the AgentRein SDK and invokes external APIs directly is not blocked by the server. AgentRein does not expose a pre-execution authorize endpoint.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.