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

# Policies

> Declarative spending rules. Server-enforced. Agents cannot bypass their own rules.

A policy is a JSON-serializable rule-set attached to an agent. Exactly one policy per agent, mutable. The [policy engine](/concepts/control) evaluates a policy on every intent, grant, issue, redeem, and checkout — pure-function, deterministic, fully testable.

Agents can **read** their policy but never modify it. Modification is dashboard or API-key only — agent tokens always get 403.

## Enforcement levels

| Level     | Behavior                                        |
| --------- | ----------------------------------------------- |
| `enforce` | Block the transaction. Returns `policy_denied`. |
| `approve` | Allow but flag for human approval.              |
| `warn`    | Log an advisory; transaction proceeds.          |

## Field reference

### Limits

| Field                   | Type   | Notes                       |
| ----------------------- | ------ | --------------------------- |
| `maxTransactionEuros`   | number | Per-transaction cap         |
| `dailyLimitEuros`       | number | UTC day rolling sum         |
| `weeklyLimitEuros`      | number | ISO week, resets Monday     |
| `monthlyLimitEuros`     | number | Calendar month              |
| `autoApproveLimitEuros` | number | Below this, no human needed |
| `requireApprovalAbove`  | number | Above this, human required  |

### Merchant + geo

| Field                 | Type      | Notes                            |
| --------------------- | --------- | -------------------------------- |
| `merchantAllowlist`   | string\[] | Allowlist of merchant names      |
| `merchantBlocklist`   | string\[] | Blocklist                        |
| `allowedMccs`         | string\[] | MCC codes                        |
| `blockedMccs`         | string\[] | MCC codes                        |
| `allowedCountries`    | string\[] | ISO 3166-1 alpha-2               |
| `blockedCountries`    | string\[] | ISO 3166-1 alpha-2               |
| `lockToFirstMerchant` | boolean   | Lock card to first merchant seen |

### Time + cooldown

| Field                                 | Type     | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `activeHoursStart` / `activeHoursEnd` | int 0–23 | UTC hour window             |
| `timezone`                            | string   | IANA tz string              |
| `allowedDays`                         | enum\[]  | `mon`–`sun`                 |
| `cooldownMinutes`                     | int      | Min minutes between charges |

### Lifecycle

| Field                 | Type | Notes                         |
| --------------------- | ---- | ----------------------------- |
| `expiresAfterMinutes` | int  | Auto-expire policy            |
| `expirationAction`    | enum | `freeze` · `close` · `notify` |
| `maxUsageCount`       | int  | Lock card after N charges     |

### Required behavior

| Field                      | Type    | Notes                                              |
| -------------------------- | ------- | -------------------------------------------------- |
| `requireIntent`            | boolean | **Sacred — defaults true, never silently dropped** |
| `requireAttestation`       | boolean | Require signed attestation per charge              |
| `attestationWindowMinutes` | int     | Validity window for attestation                    |
| `amountTolerancePercent`   | number  | Allowed deviation actual vs expected               |

## Create a policy

```bash theme={}
curl -X POST https://api.getovra.com/policies \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Subscriptions only",
    "description": "Recurring SaaS, sub EUR 250",
    "enforcementLevel": "enforce",
    "maxTransactionEuros": 250,
    "monthlyLimitEuros": 1000,
    "merchantAllowlist": ["hetzner.com", "openai.com", "anthropic.com"],
    "allowedCountries": ["DE", "US", "GB"],
    "autoApproveLimitEuros": 50
  }'
```

## Update a policy

```bash theme={}
curl -X PATCH https://api.getovra.com/policies/po_... \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monthlyLimitEuros": 1500 }'
```

Updates propagate live — including to the card-issuer-native control surface.

## Pre-built presets

`policy-presets.ts` ships templates for common patterns:

<AccordionGroup>
  <Accordion title="Travel only">
    Allowed MCCs: 4111, 4112, 4131, 4511, 7011, 7012. Country allowlist matches your travel countries. Hard daily cap.
  </Accordion>

  <Accordion title="Subscriptions">
    Merchant allowlist of known SaaS providers. `lockToFirstMerchant` true. Monthly cap.
  </Accordion>

  <Accordion title="Dev tools">
    MCC 5734/5735/7372 (software). Per-transaction ceiling. Auto-approve sub-€20.
  </Accordion>
</AccordionGroup>

## Risk thresholds (per-policy)

You can override the default 70/85/95 risk thresholds per policy:

```bash theme={}
curl -X PATCH https://api.getovra.com/risk/config \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{
    "thresholdReview": 60,
    "thresholdDeny": 80,
    "thresholdFreeze": 95,
    "autoFreezeEnabled": false
  }'
```

Constraint: `thresholdReview < thresholdDeny < thresholdFreeze`. See [Control](/concepts/control) for risk engine details.

## Surfaces

| Surface   | Capability                                      |
| --------- | ----------------------------------------------- |
| REST      | `/policies`, `/risk/config`, `/risk/violations` |
| SDK       | `ovra.policies.*`                               |
| MCP       | `ovra_policy` (read-only)                       |
| Dashboard | `/dashboard/policies`, `/dashboard/risk`        |

## Next

<CardGroup cols={2}>
  <Card title="Control" icon="shield-check" href="/concepts/control">
    The two engines that read policy and risk together.
  </Card>

  <Card title="Intents" icon="file-signature" href="/concepts/intents">
    What policy decisions are made against.
  </Card>

  <Card title="Cards" icon="rectangle" href="/concepts/cards">
    How policy syncs to card-issuer-native controls.
  </Card>
</CardGroup>