Machine View
Approval Workflows for Agent Payments
Source: https://conto.finance/docs/guides/approval-workflows
# Approval Workflows for Agent Payments
> Configure multi-step approval workflows, escalation paths, and external approval channels for high-risk agent payments.
- 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: Guides
# 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
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. A matching workflow can therefore hold an
otherwise policy-approved request until the required approvers make a decision.
If the policy engine itself requires human approval and no custom workflow matches, Conto creates a
one-review approval request for an authorized Owner, Admin, or Manager. This system-managed fallback
does not allow self-approval: the person or agent that initiated the payment cannot clear their own
held request. The payment response includes the approval request ID and status URL so your
integration can track the review to completion.
### 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` | Specific agent frameworks or classes |
| `newRecipients` | First-time recipients |
| `counterpartyTrustLevels` | Selected trust levels, such as unknown or suspicious |
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` lets you bind a workflow to selected agents without applying the same review path to
every agent in the organization.
## Workflow Settings That Matter
| Setting | What it does |
| ----------------------------------- | --------------------------------------------------------- |
| `priority` | Higher-priority workflows match first |
| `approvals.required` | Number of approvals needed before a payment moves forward |
| `expiresAfterHours` | Expiration window for pending requests |
| `approvals.allowRequester` | Whether the requester can approve their own request. Defaults to `false` |
| `approvals.approvers.roles` | 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.order` | Uses `sequential` for ordered approval |
Info:
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.
The approval decision, request state, and audit entry commit in one database transaction. A
successful response therefore never represents a decision whose audit record was silently dropped. When a decision is final, Conto also emits an `approval.approved` or `approval.denied` webhook to your organization webhook URL (see [Webhooks](https://conto.finance/guides/webhooks)).
Before a managed wallet sends funds, Conto also re-evaluates the current policy set and fails closed
if the controls deny the payment or cannot be evaluated.
## Configure Workflows Through the API
Use the authenticated workflow API when approval routing is managed from your own control plane or
infrastructure-as-code process:
| 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 |
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": ["member_finance", "member_security"]
}
},
"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
requires specific members, and the `membershipIds` order defines the approval steps. 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.
## 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](https://conto.finance/guides/external-approvals).
## 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 | Preventing agents from sending funds to unknown addresses without review |
### 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 + 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: Agent-specific review in a shared organization
| Setting | Example |
| ------------------ | ---------------------------------------------- |
| Trigger | `minimumAmount = 0`, `agentIds = ["agent_ap"]` |
| Required approvals | `1` |
| Best for | Giving one agent a dedicated approval path |
## 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
### External Approvals
Link: https://conto.finance/guides/external-approvals
Connect Slack, email, Telegram, WhatsApp, or webhooks
### Trust Scoring
Link: https://conto.finance/guides/trust-scoring
Use counterparty trust as an approval trigger
### Securing Agents
Link: https://conto.finance/guides/securing-agents
See where approvals fit in a layered policy model
### Architecture Patterns
Link: https://conto.finance/guides/architecture-patterns
Visual reference for approval and payment flows