# Approvals

> Route high-risk agent payments to reviewers with timeouts and escalation, and notify approvers by email, Slack, Telegram, WhatsApp, or webhook.

- Human URL: https://conto.finance/docs/guides/approval-workflows
- Raw Markdown: https://conto.finance/docs/guides/approval-workflows.md
- Terminal view: https://conto.finance/ai/docs/guides/approval-workflows

Documentation group: Spending controls

An approval workflow holds matching agent payments until the required reviewers approve them.
Payments that match no workflow follow your policies.

The dashboard review shows the full destination address, the network, the paying wallet, and the policy rule that held the payment. A recipient name comes from the agent and is shown as an unverified label. Approving asks you to confirm the amount and destination address before Conto records the decision.

Each approval records the reviewer’s decision. If more approvals are needed, Conto shows how many remain. The final approval submits a managed payment, which still needs confirmation. A simulated payment is reported as a completed test. If a decision response is lost, refresh the request to check its status before trying again.

A connected-card credential request that needs review goes through the same workflows, so the routing, quorum, sequential approval, and self-approval rules on this page apply to it. The final approval only lets the agent retry the request, and Conto rechecks the card’s rules then. Until the agent gets the credential, a reviewer can still reject an approved request. See [connected-card review](https://conto.finance/docs/guides/connected-cards#make-a-purchase).

Approval-link previews and decisions at `/api/approvals/action` have a 64 KiB (65,536-byte)
request-body limit. An oversized request returns HTTP 413 without consuming the action token
or recording a decision. See [action token security](https://conto.finance/docs/integrations/notification-channels#email-action-token-security).

## How the flow works

    When an agent requests a payment, Conto runs your policies and looks for a matching approval
    workflow. If none matches, the policy decision stands.

    Conto notifies the workflow's channels: Slack, email, Telegram, WhatsApp, or a webhook.

    Reviewers approve or reject in the dashboard, from the email link, or on a review page the agent
    opens from its chat. The request stays pending until it has the required approvals. If a
    workflow sets `escalation` and the request is still pending after `escalation.afterHours`, its
    escalation targets can decide it too.

    With the required approvals, Conto approves the request and submits the managed payment. Any
    rejection denies it. Either way, Conto writes the audit log, sends a webhook, and records the
    channel.

## How Conto matches a workflow

Conto evaluates active workflows in priority order and picks the first one whose trigger conditions
match the payment context. Matching runs for every payment that policy does not deny, so a matching
workflow can hold a policy-approved payment until the required approvers decide.

If a policy requires approval and no custom workflow matches, Conto creates a one-review request for
an Owner, Admin, or Manager. The person or agent that started the payment cannot approve it. The
payment response includes the approval request ID and status URL so your integration can track the
review to completion.

This fallback uses Conto's built-in policy review workflow. You can read it, but cannot edit or
delete it. Those API calls return `403 SYSTEM_WORKFLOW_READ_ONLY`. Create a custom workflow to
choose different reviewers, approval counts, or timeouts.

### Supported trigger conditions

| Trigger                   | What it matches                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `minimumAmount`           | Amounts at or above a threshold                                                                               |
| `currency`                | Currency-specific review                                                                                      |
| `categories`              | Category-based review, such as vendor or infrastructure spend                                                 |
| `agentIds`                | A specific set of agent IDs inside the organization                                                           |
| `agentTypes`              | `OPENAI_ASSISTANT`, `ANTHROPIC_CLAUDE`, `AUTOGPT`, or `CUSTOM`                                                |
| `newRecipients`           | Payments to an address your organization has not paid before. Applies to production and non-production agents |
| `counterpartyTrustLevels` | `TRUSTED`, `VERIFIED`, `UNKNOWN`, `SUSPICIOUS`, or `BLOCKED`                                                  |

A `categories` trigger ignores case and surrounding spaces. When a person has reviewed the payee and
given it a category, Conto uses that category instead of the one the agent sent. A payment with no
category matches a `categories` trigger, as long as the workflow's other triggers match too.

## Workflow settings that matter

| Setting                             | What it does                                                                                                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `priority`                          | Higher-priority workflows match first                                                                                                                                           |
| `approvals.required`                | Approvals needed, 1 to 10. Defaults to `2`                                                                                                                                      |
| `expiresAfterHours`                 | Hours a request stays pending, 1 to 168. Defaults to `24`                                                                                                                       |
| `approvals.allowRequester`          | Whether the requester can approve their own request. Defaults to `false`                                                                                                        |
| `approvals.approvers.roles`         | With `approvers.type: "roles"`. Defaults to `OWNER` and `ADMIN`. Approval-capable roles only: `OWNER`, `ADMIN`, or `MANAGER`. Read-only roles (`VIEWER`, `MEMBER`) are rejected |
| `approvals.approvers.membershipIds` | Explicit organization members allowed to approve. Each must hold an approval-capable role                                                                                       |
| `approvals.approvers.people`        | With `approvers.type: "agent_people"`: `agent_owner`, `team_manager`, or both. See [route to the agent's owner and team manager](#route-to-the-agents-owner-and-team-manager)   |
| `approvals.approvers.fallbackRoles` | With `approvers.type: "agent_people"`: roles that decide a step nobody named can decide                                                                                         |
| `approvals.order`                   | Uses `sequential` for ordered approval                                                                                                                                          |
| `escalation.afterHours`             | Hours a pending request waits before it escalates. Must be less than `expiresAfterHours`                                                                                        |
| `escalation.roles`                  | Roles that can also decide the request after it escalates: `OWNER`, `ADMIN`, or `MANAGER`                                                                                       |
| `escalation.membershipIds`          | Members who can also decide the request after it escalates                                                                                                                      |

Info:

  Any rejection ends the request. When the final approval is recorded, Conto executes a
  managed-wallet payment, and the review shows the transaction hash and explorer URL. If execution
  fails, the approval stays recorded and the request shows that execution needs attention. Conto
  does not submit payments from external or smart-contract wallets. The agent sends those transfers
  and confirms them. For an external wallet, the final approval reserves the amount and rechecks
  policy, then the agent sends the transfer and confirms it within 24 hours. A managed-wallet
  payment that did not execute right away can be retried for 24 hours after the final approval, then
  it expires. See [wallet custody](https://conto.finance/docs/guides/custody-modes).

When `allowRequester` is `false`, the owner of the agent that asked for a payment or checkout
cannot approve it while another member of your organization could. If nobody else can approve, the
owner still can. Payments held by a policy rule with no matching workflow are not affected.

Changing `approvals.required` applies to new requests. A request already waiting still needs the
number of approvals it was created with, and one rejection always ends it. A held agent-to-agent
payment reads the current number instead.

When a decision is final, Conto sends `approval.approved` or `approval.denied` to your organization
event webhook (see [two kinds of webhooks](https://conto.finance/docs/guides/webhooks#two-kinds-of-webhooks)). Notification
channels subscribed to `approval.decided` get that event instead. Before a managed wallet sends
funds, Conto rechecks current policy and stops the payment if the check denies it or cannot run.

<span id="route-to-the-agents-owner-and-team-manager" />

### Route to the agent's owner and team manager

With `approvers.type: "agent_people"`, Conto finds the approvers from the agent that asked for the
payment: `agent_owner` is the agent's owner, and `team_manager` is any manager of the agent's
[team](https://conto.finance/docs/policies/overview). Team managers are found when someone decides, so a new team manager can
decide requests already waiting. The owner step stays with the person who owned the agent when the
request was created. If the agent has a new owner by then, neither person fills that step as its
owner, and it goes to `fallbackRoles`. Only an Owner or Admin can change an agent's owner.

- With `order: "sequential"`, each entry in `people` is one step, in the order given, and
  `approvals.required` must equal the number of steps. `["agent_owner", "team_manager"]` asks the
  owner first, then the manager.
  Everyone who approves a later step gets the email up front. A decision before their turn is
  refused with `409`, and their link stays usable for their turn.
- With `order: "any_order"`, the entries can approve in any order, and `approvals.required` can be
  at most the number of entries. Each approval fills one entry. With
  `["agent_owner", "team_manager"]` and two required, once the owner approves only a team manager
  can give the second approval, and once a team manager approves only the owner can.
- A step goes to `fallbackRoles` when the agent has no owner or a new one, its team has no manager,
  that person cannot approve payments, or that person already decided another step. If an edit
  leaves fewer `people` than a waiting request needs, `fallbackRoles` give the remaining approvals.
  If nobody can decide an owner step through `fallbackRoles`, your organization's Owners can, so an
  owner change cannot leave a request nobody can decide.
  An active `MEMBER` can fill their own agent-owner step; team managers and fallback approvers must
  hold `OWNER`, `ADMIN`, or `MANAGER`.
- The owner can approve on the owner step even when `allowRequester` is `false`, because the owner
  is the person behind the agent's payments. On the manager step and the fallback, the requester
  rule above applies.

```json
"approvals": {
  "required": 2,
  "order": "sequential",
  "allowRequester": false,
  "approvers": {
    "type": "agent_people",
    "people": ["agent_owner", "team_manager"],
    "fallbackRoles": ["OWNER", "ADMIN"]
  }
}
```

For a third review above a larger amount, add a second workflow with a higher `priority` and a
higher `minimumAmount` that names finance roles or members.

### Escalation

Conto checks pending requests every 15 minutes. A request that is still pending
`escalation.afterHours` after it was created escalates once.

- The escalation roles and members can then approve or reject it in the dashboard, from the
  approval email, or with the assistant. The workflow's own approvers can still decide too.
- In a sequential workflow, an escalation target can decide out of turn. Their decision counts as
  the next step.
- Escalation targets follow the same rules as every approver. They must be members of your
  organization with the `OWNER`, `ADMIN`, or `MANAGER` role, and the requester cannot approve their
  own request unless `approvals.allowRequester` is `true`. For dynamic approvers, the explicit
  agent-owner exception applies only while that owner step is open; escalation cannot bypass it
  to let the requester decide a manager step.
- Escalation does not extend the request. It still expires `expiresAfterHours` after it was
  created.
- Channels subscribed to `approval.escalated` send the request again to every approver who has not
  decided, including the escalation targets. To email a target their own Approve and Reject links,
  add their sign-in email to an email channel's recipients.

## Review decisions in Inbox

Open **Inbox > Needs decision** to review pending payments, card requests, tasks, budget requests,
and account changes. Requests with the earliest expiry appear first. **Alerts** contains notices
you can acknowledge; acknowledging a notice does not approve a purchase. Completed decisions
appear in **History**.

## Configure workflows in the dashboard

Open **Policies → Approvers**. Owners and Admins can create and edit a workflow, choose
the agents and purchase conditions it matches, and configure reviewers, required approvals,
ordered review, expiry, and escalation. Managers and Viewers can inspect workflows without changing them.
A team manager is not automatically a purchase reviewer; set reviewers explicitly.

For checkout checkpoints, a policy must require review before the workflow routes that held purchase.
See [Conto with Stripe Link](https://conto.finance/docs/guides/stripe-link#manage-several-agents) for the checkout-specific flow.

## Configure workflows through the API

Create and manage workflows with this API or by asking the Conto assistant. For a single review above an amount, set **Require Approval Above** on a policy rule
instead.

| Method   | Endpoint                               | Purpose                                   |
| -------- | -------------------------------------- | ----------------------------------------- |
| `GET`    | `/api/approval-workflows`              | List workflows and filter by `enabled`    |
| `POST`   | `/api/approval-workflows`              | Create a workflow                         |
| `GET`    | `/api/approval-workflows/{workflowId}` | Read one workflow                         |
| `PATCH`  | `/api/approval-workflows/{workflowId}` | Update supported workflow settings        |
| `DELETE` | `/api/approval-workflows/{workflowId}` | Delete a workflow with no pending reviews |

An agent's admin SDK key cannot create, change or delete a workflow, whichever agents it covers.
The first matching workflow decides how many approvals a payment needs, so any of those changes
could loosen another agent's control. These requests return `403` with code
`AGENT_KEY_WORKFLOW_FORBIDDEN`, or `AGENT_SELF_CONTROL_FORBIDDEN` when the workflow can hold the
key's own agent's payments. Use a signed-in session or an organization API key.

Create a sequential two-person review:

```bash
curl -X POST https://conto.finance/api/approval-workflows \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Large treasury payments",
    "description": "Two reviewers for large transfers",
    "triggers": {
      "minimumAmount": 5000,
      "currency": "USDC"
    },
    "approvals": {
      "required": 2,
      "order": "sequential",
      "allowRequester": false,
      "approvers": {
        "type": "specific_members",
        "membershipIds": ["cmm59z8k40001abcd1234efgh", "cmm59z9m20002abcd5678ijkl"]
      }
    },
    "expiresAfterHours": 24,
    "escalation": {
      "afterHours": 4,
      "roles": ["OWNER"],
      "membershipIds": []
    },
    "priority": 50,
    "enabled": true
  }'
```

The response returns the stable workflow ID, normalized triggers, reviewer selection, ordered
`steps` for sequential review, timeout, escalation targets, enabled state, usage count, and
timestamps.

Use `GET /api/organizations/me/members` to find reviewer membership IDs. A sequential workflow
uses specific members, whose `membershipIds` order defines the approval steps, or `agent_people`,
whose `people` order does. A role-based workflow uses `order: "any_order"`.

`PATCH` updates only the fields you send, except `triggers`, which replaces the current trigger set.
Deletion returns `WORKFLOW_HAS_PENDING_REQUESTS` until the workflow's active reviews are resolved.

## Notify approvers

Conto sends each approval request to every active notification channel subscribed to
`approval.requested`. New organizations start with an **Owner email** channel. Owners and Admins
add channels in **Settings > Notifications**. Email links can approve or reject once the approver
signs in to Conto as the member the email was sent to. Slack, Telegram, WhatsApp, and webhook
messages link to the review in Conto. See
[notification channels](https://conto.finance/docs/integrations/notification-channels) for channel setup, a test approval,
and troubleshooting.

Subscribe channels to `approval.requested`, plus `approval.escalated` if a workflow sets
`escalation`. On a webhook notification channel, also enable `approval.decided` and
`approval.expired`, plus `payment.executed` if your system marks invoices as paid.

Conto queues each notification with the change it announces and retries it until it is delivered.
`approval.expired` is sent whenever a request runs out of time, including when someone tries to
decide it after its deadline.

  Email and dashboard decisions follow the same rules. The deciding member must hold `OWNER`,
  `ADMIN`, or `MANAGER`, except that an active `MEMBER` can fill the current owner step for their
  own agent. Listing a Member in a role-based workflow or escalation does not grant that exception.
  `VIEWER` cannot approve payments. The agent-owner requester exception applies only on the owner
  step.

<span id="review-from-your-agents-chat" />

## Review from your agent's chat

An agent using the Conto MCP server can open the review for a payment it is waiting on. It calls
`review_payment_approval`, and you get a review page for that one payment, either as a prompt from
your MCP client or as a link the agent shows you. Sign in to Conto there and approve or reject.

- The page shows the amount, the recipient or merchant, the agent and its purpose, why the payment
  needs review, and whether approval sends it right away or lets the agent finish the next step.
- Opening the page approves nothing. The same workflow rules apply as in the dashboard: approver
  roles, specific approvers, sequential order, required approvals, and self-approval.
- If the payment changes after review started, the page refuses a decision. Ask the agent to start
  review again.
- A review link expires after 30 minutes. The approval request itself keeps its own expiry.
- The agent reads the recorded decision and continues the same payment. It does not create a new
  one.

See [`review_payment_approval`](https://conto.finance/docs/mcp/tools#review_payment_approval) for the tool.

## Recommended patterns

### Pattern 1: single approval for large payments

| Setting            | Example                                                   |
| ------------------ | --------------------------------------------------------- |
| Trigger            | `minimumAmount = 100`                                     |
| Required approvals | `1`                                                       |
| Approver roles     | `OWNER`, `ADMIN`                                          |
| Best for           | Day-to-day spend that only needs review above a threshold |

### Pattern 2: review first-time recipients

| Setting            | Example                                                       |
| ------------------ | ------------------------------------------------------------- |
| Trigger            | `newRecipients = true`                                        |
| Required approvals | `1`                                                           |
| Approver roles     | `ADMIN`                                                       |
| Best for           | Agents paying addresses your organization has not paid before |

### Pattern 3: dual control for sensitive transfers

| Setting            | Example                                              |
| ------------------ | ---------------------------------------------------- |
| Trigger            | `minimumAmount = 5000`                               |
| Required approvals | `2`                                                  |
| Self approval      | `false`                                              |
| Best for           | Treasury, vendor onboarding, or high-value transfers |

### Pattern 4: sequential approval for finance and security

| Setting            | Example                                                           |
| ------------------ | ----------------------------------------------------------------- |
| Specific approvers | `finance lead`, then `security lead`                              |
| Order              | `sequential`                                                      |
| Best for           | Controls that require ordered sign-off from multiple stakeholders |

### Pattern 5: agent-specific review in a shared organization

| Setting            | Example                                                         |
| ------------------ | --------------------------------------------------------------- |
| Trigger            | `minimumAmount = 0`, `agentIds = ["cmm5a7agt008t49h7bjqza99x"]` |
| Required approvals | `1`                                                             |
| Best for           | Giving one agent a dedicated approval path                      |

## Related guides

### Notification channels
Link: https://conto.finance/docs/integrations/notification-channels

    Channel fields, payloads, and signatures

### Trust scoring
Link: https://conto.finance/docs/guides/trust-scoring

    Use counterparty trust as an approval trigger

### Recommended policy setup
Link: https://conto.finance/docs/policies/overview#recommended-setup

    See where approvals fit in a layered policy model

### Wallet custody
Link: https://conto.finance/docs/guides/custody-modes

    Diagrams of the managed and external wallet payment flows
