# Set policies

[API Documentation](https://docs.catena.com/api/get-policy.md)

A policy is a set of rules attached to one or more agents. Put simply, it
decides what an agent is allowed to do: which capabilities the agent has, which
accounts and [counterparties](https://docs.catena.com/counterparties.md) it can use, how much it can move,
and which actions need a person's approval.

Admins write policies and assign them to agents. An admin can edit an agent's
policy, or assign it a different one, at any time.

## Capabilities

A policy grants three capabilities, and each one is turned on and configured
separately:

| Capability | What it grants                                                                                                                                |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| View       | Which accounts the agent can read balances and history from.                                                                                  |
| Transfer   | Moves between your own accounts: which accounts, and the limits.                                                                              |
| Send       | Payments to counterparties: which accounts to send from, spending rules, when a payment needs approval, and which counterparties are allowed. |

In addition, a policy can allow the agent to:

- Create new counterparties.
- Request payment details from existing counterparties.
- Request temporary increases to its limits.

An agent with no policy can identify itself and nothing else, which means it
cannot read any account.

## Spending rules

Spending rules limit sends and transfers. Each rule caps one of the following:

- The amount of a single transaction (a per-transaction limit).
- The total amount per day, week, or month (e.g., a daily limit).
- The number of transactions per day, week, or month.

Every rule also has a consequence (block or require approval). When an action
crosses the rule, we will either block the action or route it to a person for
approval. A blocked action is final. A routed action will wait in
[**Approvals**](https://docs.catena.com/approvals.md) until an admin approves or denies it.

Every rule that applies to an action must pass.

For example, let's say Cora's Coffee gives its purchasing agent a rule that caps
sends at $500.00 per day, with approval as the consequence. In the morning, the
agent pays Pete's Packaging $300.00 by ACH, which stays under the cap. In the
afternoon, it tries to pay Pete's Packaging another $250.00. That send would
bring the day's total to $550.00, so it crosses the rule and will wait in
**Approvals** until an admin approves or denies it.

### One account or all accounts

A rule applies either to a single account or to all of the policy's accounts
combined. A rule for all accounts sets one total, shared across every account
the agent sends from. If you'd like each account to have its own limit, write
one rule per account.

Note that we count sends and transfers separately. A transfer between your own
accounts does not count toward the agent's send limit, and a send does not count
toward its transfer limit.

## Counterparty access

The Send capability lists the counterparties the agent can pay. If a
counterparty is outside that list, it won't appear in
`catena counterparties list`, and the agent cannot send to it.

Approving a new counterparty adds it to your organization. However, the agent
can only pay it when its policy allows sends to that counterparty.

## The default policy

When an admin sets up wallet security, Catena creates the organization's first
account and a **Default Policy**. The approval screen then selects the Default
Policy for each new agent (the approver can choose a different one).

| Organization | What the Default Policy allows                                                                                                                                                                        |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Live         | The agent can read its accounts, add new counterparties, and send from the starting account. Sends above a small amount wait for approval. Sends past the per-transaction or daily limit are blocked. |
| Sandbox      | The agent can read every account and send test funds back to the Catena counterparty. It can do nothing else.                                                                                         |

## Create and edit policies

Policies have their own page in the console (**Policies**), which includes
starter templates to begin from. An admin can also open **Edit policy** from an
agent's page. On that page, click the agent's policy to see its current limits
and to change or remove it.

## Check an agent's policy

To see what an agent is allowed to do, run:

```sh
catena policy show
```

We recommend that an agent run this command whenever the user asks what it is
allowed to do.

## Temporary overrides

When a policy blocks a task the user asked for, the agent can ask an admin to
raise the one limit that stopped it, for a set time (the console calls these
_temporary grants_). To allow them, an admin sets **Temporary grant requests**
to **Require approval** in the policy's **Payments** section.

```sh
catena policy request-override --account acct_... \
  --amount 500 --duration 4h \
  --reason "Vendor invoice INV-4471 is $420"
```

Below are the rules that overrides follow:

| Rule             | Detail                                                                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Approval         | The request waits for a person, and nothing changes before it is approved.                                                                            |
| Capability       | By default, the request raises a send limit. Pass `--capability transfer` to raise a transfer limit, in which case `--account` is the source account. |
| Scope            | Pass `--all-accounts` instead of `--account` to raise a limit shared across all accounts.                                                             |
| Duration         | Durations run from one minute to seven days (e.g., `--duration 4h`). The override expires on its own and needs no cleanup.                            |
| Pending requests | Each agent can have one pending request at a time.                                                                                                    |
| Agent            | An override applies only to the agent that requested it. While the override is active, edits to that agent's base policy have no effect on it.        |

Once the override is approved, the agent runs the blocked command again, with a
new [idempotency key](https://docs.catena.com/intents.md#retry-safely) if it passed one. See
[Raise a limit for one task](https://docs.catena.com/recipes/raise-a-limit.md) for a full walkthrough.

## Related

- [Handle approvals](https://docs.catena.com/approvals.md): Learn what goes to the approvals queue, who can approve, when requests expire, and what happens between an approval and a completed payment.
- [Intents and retries](https://docs.catena.com/intents.md): Learn how an intent moves through its statuses and resolutions, which fields explain its result, and how to retry safely with idempotency keys.
- [Raise a limit for one task](https://docs.catena.com/recipes/raise-a-limit.md): When a single limit blocks a task, your agent can ask an admin to raise it for a while, and then finish the task once the admin approves.