Set policies

API Documentation

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 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:

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 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).

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:

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.

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

Below are the rules that overrides follow:

Once the override is approved, the agent runs the blocked command again, with a new idempotency key if it passed one. See Raise a limit for one task for a full walkthrough.