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

# MAIP policies

> Define runtime enforcement rules that control what AI agents can do based on trust scores, scopes, delegation depth, and agent type.

MAIP policies let you enforce guardrails on AI agent behavior at runtime. When an agent requests access to a scoped resource, all active policies are evaluated before the action proceeds. If any policy denies the request, the action is blocked.

<Note>
  MAIP policies are different from [issuance policies](/guides/issuance-policies). Issuance policies govern **credential minting and verification** for human users and issuers. MAIP policies govern **machine agent behavior** at runtime — controlling what agents can do based on trust scores, delegation depth, scopes, and agent type.
</Note>

## When to use MAIP policies

Use MAIP policies when you need to:

* Block agents with low trust scores from performing sensitive operations
* Require human approval when an agent is deep in a delegation chain
* Restrict specific agent types (e.g., `llm` or `worker`) from accessing certain scopes
* Enforce different rules for different risk levels without changing agent code
* Add runtime guardrails to multi-agent orchestration workflows

If you don't create any MAIP policies, agent access is controlled only by scope assignments and agent status.

## How policies work

Each MAIP policy contains one or more **rules**. Each rule has:

* **Conditions** — field-level checks evaluated against the requesting agent's context
* **Effect** — `allow`, `deny`, or `require_approval`
* **requires\_approval** — optional flag that triggers a human approval workflow

Rules within a policy are evaluated independently. If **any** rule with a `deny` effect matches, the action is blocked regardless of any `allow` rules. This is a **deny-overrides** model.

```
Agent requests scope → Evaluate all active policies (priority order)
                              │
                     ┌────────┼────────┐
                     ▼        ▼        ▼
                  Policy A  Policy B  Policy C
                  (p: 10)   (p: 20)  (p: 100)
                     │        │        │
                     ▼        ▼        ▼
               Any deny? ──yes──→ Action BLOCKED
                  │
                  no
                  │
                  ▼
             Action ALLOWED
```

### Evaluation order

1. **Agent status** — the agent must be `active`. Suspended or revoked agents are always denied.
2. **Scope check** — the requested scope must be in the agent's granted scopes. Explicitly denied scopes (prefixed with `!`) always block access.
3. **Policy rules** — all active tenant policies are evaluated in priority order (lower numbers first). Each rule's conditions are AND-ed.

### Condition fields

| Field              | Type   | Operators                    | Description                                        |
| ------------------ | ------ | ---------------------------- | -------------------------------------------------- |
| `trust_score`      | number | `lt`, `gt`, `le`, `ge`       | Agent's current trust score (0.0–1.0)              |
| `scope`            | string | `eq`, `ne`, `in`, `contains` | The scope being requested (e.g., `data:write`)     |
| `agent_type`       | string | `eq`, `ne`, `in`             | Agent type (e.g., `llm`, `worker`, `orchestrator`) |
| `delegation_depth` | number | `gt`, `ge`, `lt`, `le`       | Position in the delegation chain (0 = direct)      |

### Operators

| Operator   | Description                 | Example value       |
| ---------- | --------------------------- | ------------------- |
| `eq`       | Equals                      | `"data:write"`      |
| `ne`       | Not equals                  | `"system"`          |
| `lt`       | Less than                   | `0.5`               |
| `gt`       | Greater than                | `3`                 |
| `le`       | Less than or equal          | `0.3`               |
| `ge`       | Greater than or equal       | `0.7`               |
| `in`       | Matches any value in a list | `["llm", "worker"]` |
| `contains` | String contains substring   | `"write"`           |

### Effects

| Effect             | Behavior                                                                 |
| ------------------ | ------------------------------------------------------------------------ |
| `allow`            | Explicitly allow the action. Does not override denials from other rules. |
| `deny`             | Block the action. First deny wins.                                       |
| `require_approval` | Allow the action but flag it for human approval before proceeding.       |

## Creating a policy

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.truthlocks.com/v1/maip/policies \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Block Low-Trust Write Operations",
      "description": "Deny data:write scope for agents with trust score below 0.5",
      "category": "trust",
      "priority": 10,
      "rules": [
        {
          "conditions": [
            {"field": "trust_score", "op": "lt", "value": 0.5},
            {"field": "scope", "op": "eq", "value": "data:write"}
          ],
          "effect": "deny",
          "requires_approval": false
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.truthlocks.com/v1/maip/policies", {
    method: "POST",
    headers: {
      "X-API-Key": "tl_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Block Low-Trust Write Operations",
      description: "Deny data:write scope for agents with trust score below 0.5",
      category: "trust",
      priority: 10,
      rules: [
        {
          conditions: [
            { field: "trust_score", op: "lt", value: 0.5 },
            { field: "scope", op: "eq", value: "data:write" },
          ],
          effect: "deny",
          requires_approval: false,
        },
      ],
    }),
  });
  const policy = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.truthlocks.com/v1/maip/policies",
      headers={
          "X-API-Key": "tl_live_...",
          "Content-Type": "application/json",
      },
      json={
          "name": "Block Low-Trust Write Operations",
          "description": "Deny data:write scope for agents with trust score below 0.5",
          "category": "trust",
          "priority": 10,
          "rules": [
              {
                  "conditions": [
                      {"field": "trust_score", "op": "lt", "value": 0.5},
                      {"field": "scope", "op": "eq", "value": "data:write"},
                  ],
                  "effect": "deny",
                  "requires_approval": False,
              }
          ],
      },
  )
  policy = response.json()
  ```
</CodeGroup>

All new policies are created with `status: "active"` and take effect immediately.

### Policy categories

| Category | Use case                                              |
| -------- | ----------------------------------------------------- |
| `scope`  | Restrict access based on specific scopes or resources |
| `trust`  | Restrict access based on trust score thresholds       |
| `rate`   | Restrict access frequency or volume                   |
| `custom` | Custom enforcement logic (default if omitted)         |

### Priority

The `priority` field controls evaluation order. Lower numbers are evaluated first. Range: 1–1000. Default: `100`. If multiple policies share the same priority, they are evaluated in creation order.

## Evaluating policies at runtime

Call the evaluate endpoint before your agent performs a sensitive operation. The response tells you whether the action is allowed, denied, or requires human approval.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/maip/policies/evaluate \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
    "scope": "data:write",
    "action": "update_customer_record",
    "resource": "customers/cust_12345"
  }'
```

**Allowed response:**

```json theme={null}
{
  "allowed": true,
  "requires_approval": false
}
```

**Denied response:**

```json theme={null}
{
  "allowed": false,
  "denied_by": ["Block Low-Trust Write Operations"],
  "reason": "denied by policy",
  "requires_approval": false
}
```

**Requires approval response:**

```json theme={null}
{
  "allowed": true,
  "requires_approval": true
}
```

When `requires_approval` is `true`, your application should route the action through a human approval workflow before proceeding.

## Listing policies

```bash theme={null}
curl https://api.truthlocks.com/v1/maip/policies \
  -H "X-API-Key: $API_KEY"
```

Returns all MAIP policies for your tenant, including their rules, priority, and status.

## Common patterns

### Block untrusted agents from writing data

Deny any agent with a trust score below 0.5 from accessing write scopes.

```json theme={null}
{
  "name": "Block Low-Trust Writes",
  "category": "trust",
  "priority": 10,
  "rules": [
    {
      "conditions": [
        { "field": "trust_score", "op": "lt", "value": 0.5 },
        { "field": "scope", "op": "eq", "value": "data:write" }
      ],
      "effect": "deny"
    }
  ]
}
```

### Require approval for deep delegation chains

Agents more than three levels deep in a delegation chain must get human approval for any action.

```json theme={null}
{
  "name": "Approval for Deep Delegation",
  "category": "scope",
  "priority": 20,
  "rules": [
    {
      "conditions": [
        { "field": "delegation_depth", "op": "gt", "value": 3 }
      ],
      "effect": "require_approval",
      "requires_approval": true
    }
  ]
}
```

### Restrict LLM agents from executing tools

Prevent LLM-type agents from invoking tool execution scopes while allowing other agent types.

```json theme={null}
{
  "name": "No Tool Execution for LLMs",
  "category": "scope",
  "priority": 15,
  "rules": [
    {
      "conditions": [
        { "field": "agent_type", "op": "eq", "value": "llm" },
        { "field": "scope", "op": "eq", "value": "tool:execute" }
      ],
      "effect": "deny"
    }
  ]
}
```

### Block multiple agent types from a scope

Use the `in` operator to match against a list of values instead of writing separate rules for each agent type.

```json theme={null}
{
  "name": "No Autonomous Writes",
  "category": "scope",
  "priority": 10,
  "rules": [
    {
      "conditions": [
        { "field": "agent_type", "op": "in", "value": ["llm", "worker"] },
        { "field": "scope", "op": "eq", "value": "data:write" }
      ],
      "effect": "deny"
    }
  ]
}
```

### Deny all write scopes with a single rule

Use the `contains` operator to match any scope that includes a substring, rather than listing each write scope individually.

```json theme={null}
{
  "name": "Read-Only for Low Trust",
  "category": "trust",
  "priority": 10,
  "rules": [
    {
      "conditions": [
        { "field": "trust_score", "op": "lt", "value": 0.5 },
        { "field": "scope", "op": "contains", "value": "write" }
      ],
      "effect": "deny"
    }
  ]
}
```

### Combine multiple rules in one policy

A single policy can contain multiple rules for layered enforcement:

```json theme={null}
{
  "name": "Production Safety Net",
  "category": "custom",
  "priority": 5,
  "rules": [
    {
      "conditions": [
        { "field": "trust_score", "op": "lt", "value": 0.3 }
      ],
      "effect": "deny"
    },
    {
      "conditions": [
        { "field": "trust_score", "op": "lt", "value": 0.7 },
        { "field": "scope", "op": "eq", "value": "data:write" }
      ],
      "effect": "require_approval",
      "requires_approval": true
    }
  ]
}
```

This policy blocks agents with trust scores below 0.3 outright, and requires human approval for write operations from agents scoring between 0.3 and 0.7.

## MAIP policies vs. RBAC policies

|                      | MAIP policies                                            | RBAC (issuance) policies                                    |
| -------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
| **Governs**          | Machine agent runtime behavior                           | Credential minting, verification, and export                |
| **Subjects**         | AI agents identified by MAIP ID                          | Human users and issuers                                     |
| **Condition fields** | `trust_score`, `scope`, `agent_type`, `delegation_depth` | `jurisdiction`, `trust_tier`, `risk_rating`, `key.age_days` |
| **Evaluation model** | Deny-overrides (any deny blocks)                         | First-match wins                                            |
| **API path**         | `/v1/maip/policies`                                      | `/v1/policies`                                              |

## Related

<CardGroup cols={2}>
  <Card title="MAIP Policies API reference" icon="rectangle-terminal" href="/api-reference/machine-identity/policies/list">
    Create, list, and evaluate MAIP policies via the REST API.
  </Card>

  <Card title="Trust scores" icon="chart-line" href="/guides/trust-scores">
    Understand the trust scoring system that feeds into policy conditions.
  </Card>

  <Card title="Agent authorization" icon="key" href="/guides/agent-authorization">
    Scope-based authorization and session management for agents.
  </Card>

  <Card title="Machine identity" icon="fingerprint" href="/guides/machine-identity">
    Full overview of the Machine Agent Identity Protocol.
  </Card>
</CardGroup>