> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Approval Workflows for Agent Payments
> Configure multi-step approval workflows, escalation paths, and external approval channels for high-risk agent payments.
# Approval Workflows for Agent Payments
Approval workflows let you keep low-risk agent payments fast while routing exceptional cases through
human review. In Conto, approvals are part of the payment control center, not an afterthought layered
on later.
## When to Use Approval Workflows
Approval workflows are a strong fit when you need any of the following:
* Payments above a finance threshold
* New recipients that have not built trust yet
* Category-specific review, such as treasury or vendor onboarding flows
* Role-based approvals for finance, ops, or compliance
* Dual control or sequential review for larger transfers
## How the Flow Works
```mermaid theme={null}
flowchart TD
Payment["Agent requests payment"] --> Policy["Policy engine + workflow matching"]
Policy --> Match{"Workflow matched?"}
Match -->|"No"| Continue["Normal approval / deny path"]
Match -->|"Yes"| Create["Create approval request"]
Create --> Notify["Send notifications to external channels"]
Notify --> Decision["Approver decisions"]
Decision --> Approved{"Required approvals reached?"}
Decision --> Rejected{"Any rejection?"}
Approved -->|"Yes"| Execute["Mark APPROVED and execute managed payment"]
Approved -->|"No"| Pending["Stay pending"]
Rejected -->|"Yes"| Deny["Payment status moves to DENIED"]
Rejected -->|"No"| Pending
Execute --> Receipt["Transaction submitted + explorer receipt"]
Receipt --> Audit["Audit log + webhook + channel record"]
Deny --> Audit
```
## How Conto Matches a Workflow
Conto evaluates active workflows in priority order and picks the first workflow whose trigger
conditions match the payment context.
Workflow matching runs for every non-denied payment. That means a workflow can deliberately hold an
otherwise policy-approved request, which is how verifier pilots such as Delta act as an approval
gate without becoming the settlement layer.
If the policy engine itself requires human approval and no custom workflow matches, Conto creates a
one-review approval request through a system-managed route. This guarantees that every approval
alert has a decision record that Owners, Admins, or Managers can open, approve, or reject. The
system-managed route is internal and is not listed with configurable workflows.
### Supported trigger conditions
| Trigger | What it matches |
| ------------------------ | ------------------------------------------------------------- |
| `amountThreshold` | 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` | Specific agent frameworks or classes |
| `newRecipients` | First-time recipients |
| `counterpartyTrustLevel` | Low-trust or unknown counterparties |
This makes approval workflows a good complement to trust scoring and counterparty rules. For example,
you can auto-approve trusted vendors while forcing review for unknown recipients.
`agentIds` is especially useful for staged rollouts and verifier pilots. It lets you bind a workflow
to one or two agents in a mixed org without turning on the same review path for every other agent.
## Workflow Settings That Matter
| Setting | What it does |
| -------------------- | --------------------------------------------------------- |
| `priority` | Higher-priority workflows match first |
| `requiredApprovals` | Number of approvals needed before a payment moves forward |
| `timeoutHours` | Expiration window for pending requests |
| `allowSelfApproval` | Whether the initiator can approve their own request |
| `approverRoles` | Role-based access, such as `OWNER` or `ADMIN` |
| `specificApprovers` | Explicit user allowlist for a workflow |
| `sequentialApproval` | Enforces approval order when specific approvers are set |
Any rejection ends the workflow immediately. Approvals accumulate until the required approval
count is reached. When the final approval is recorded, Conto immediately invokes the payment
execution path for Conto-managed wallets. The approval remains recorded if custody execution
fails, and the request stays visible as needing execution attention. External and smart-contract
wallets still require their manual execution and confirmation flow.
## External Approval Channels
Approval requests can be delivered to external channels so finance or ops teams can act without
logging into Conto for every review.
Supported channels include:
* Slack
* Email
* Telegram
* WhatsApp
* Webhook
Each decision records the acting channel, and Conto keeps an audit trail of who approved, when they
approved, and how the request was resolved.
For step-by-step setup, see [/guides/external-approvals](/guides/external-approvals).
## Recommended Patterns
### Pattern 1: Single approval for large payments
| Setting | Example |
| ------------------ | --------------------------------------------------------- |
| Trigger | `amountThreshold = 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 | Preventing agents from sending funds to unknown addresses without review |
### Pattern 3: Dual control for sensitive transfers
| Setting | Example |
| ------------------ | ---------------------------------------------------- |
| Trigger | `amountThreshold = 5000` |
| Required approvals | `2` |
| Self approval | `false` |
| Best for | Treasury, vendor onboarding, or high-value transfers |
### Pattern 4: Sequential approval for finance + security
| Setting | Example |
| ------------------- | ----------------------------------------------------------------- |
| Specific approvers | `finance lead`, then `security lead` |
| Sequential approval | `true` |
| Best for | Controls that require ordered sign-off from multiple stakeholders |
### Pattern 5: Scoped verifier pilot in a shared org
| Setting | Example |
| ------------------ | ----------------------------------------------------- |
| Trigger | `amountThreshold = 0`, `agentIds = ["agent_ap_demo"]` |
| Required approvals | `1` |
| Best for | Running a verifier like Delta against one agent first |
## Pair Approval Workflows with Trust Scoring
One of the highest-signal combinations is:
1. Use trust scoring to classify counterparties.
2. Let trusted or verified recipients flow normally.
3. Route unknown or deteriorating counterparties into approval workflows.
That gives you a fast path for established counterparties and a controlled path for new or risky
ones.
## Canonical Approval Architecture
The most common production stack looks like this:
* Policy engine blocks clearly disallowed payments outright.
* Trust scoring enriches the recipient before the payment is evaluated.
* Approval workflows catch the gray area between auto-approve and hard deny.
* External channels deliver requests to the real stakeholders.
* Audit logs and webhooks make the outcome visible to finance and operations systems.
## Related Guides
Connect Slack, email, Telegram, WhatsApp, or webhooks
Use counterparty trust as an approval trigger
See where approvals fit in a layered policy model
Visual reference for approval and payment flows