Approvals

Approvals are human-in-the-loop gates embedded directly in workflows. When a workflow run reaches an approval step, ProvenanceOne pauses execution, sends a structured review request to designated assignees, and waits for a decision. The run resumes only when an assignee approves or rejects. If no one acts before the SLA expires, the platform emits a breach event and escalates.

Approvals are the primary mechanism for keeping humans in control of consequential AI-driven actions: deleting records, sending bulk communications, making financial decisions, or any action where an incorrect agent output would be costly or irreversible.

---

When to use approvals

Insert an approval step whenever:

• An agent step may take an action that is difficult or impossible to reverse
• The risk of an incorrect agent output is high enough that human review is warranted before proceeding
• Regulatory or compliance requirements mandate a human sign-off on specific operations
• You want to give a human the opportunity to edit the agent's proposed action before it executes

---

Key concepts

Approval request — the structured record created when an approval step activates. Contains all the context a reviewer needs to make a decision: the action proposed, a summary, risk level, evidence, and the editable payload.

Payload — the data the downstream step will receive when the run resumes. Approvers can edit the payload before approving, allowing them to correct or refine the agent's proposed output before it takes effect.

SLA — the maximum time in minutes an approval can remain pending before the platform considers it a breach. When the SLA expires, the platform emits approval.sla_breach and notifies the assignees.

Delegated grant — a mechanism for an approver to pre-authorise a class of actions, so that similar requests can be actioned automatically without requiring a full approval review for each one.

Evidence — structured supporting data attached to an approval request to help the reviewer make an informed decision. Each evidence item has a label, a value, and a tone that signals its significance.

---

How it works

Approval lifecycle

Requested → Pending → (Viewed) → Approved | Rejected
                                 ↘ SLA Breach (if timer expires)

1. The workflow run reaches an approval step.
2. ProvenanceOne creates an approval request and transitions the run to approval status.
3. Assignees receive a notification via email (and Slack or webhook if configured).
4. An assignee opens the approval, reviews the evidence, optionally edits the payload, and approves or rejects.
5. ProvenanceOne resumes the run: if approved, execution continues with the (possibly edited) payload; if rejected, the run terminates or routes to an error branch.

Resuming execution

Approval execution is backed by the workflow orchestration service. When an assignee approves, ProvenanceOne decrypts the task token (stored encrypted with platform-managed keys as encryptedTaskToken) and calls signalling the orchestration service to resume the run. On rejection, it calls SendTaskFailure. This ensures the run resumes exactly where it paused, with the correct payload.

SLA monitoring

A serverless function runs every 5 minutes to check pending approvals against their SLA. When an SLA breach is detected:

• The approval.sla_breach audit event is emitted
• Assignees are notified via configured channels
• The approval remains pending — it does not auto-reject

Evidence tones

Evidence items use a tone to signal significance to the reviewer:

Tone	Meaning
slate	Neutral context; informational
amber	Caution; the reviewer should pay attention
red	High-risk signal; proceed carefully
emerald	Positive signal; supports approving
blue	Informational highlight

---

Approval request fields

Field	Type	Description
workspaceId	string	Workspace the approval belongs to
workflowId	string	Workflow that generated the approval
workflowName	string	Display name of the workflow
runId	string	Run that is paused waiting for this approval
stage	string	Name of the approval step in the workflow
requestedBy	string	Agent ID or "system" that requested the approval
action	string	Short description of the action to be approved
summary	string	Longer explanation of what the action will do
risk	enum	low | medium | high
slaMinutes	integer	Time limit in minutes before SLA breach
assignees	string[]	Email addresses of reviewers
rationale	string	The agent's explanation for why this action is needed
confidence	number	Agent's self-reported confidence (0–1); treat as a signal, not a guarantee
evidence	Evidence[]	Supporting data items for the reviewer
payload	object	The data that will be passed to the next step on approval; editable by the approver
upstream	UpstreamStage[]	Context from earlier steps in the run
encryptedTaskToken	string	encrypted SFN task token; not shown in the UI

---

Configuration options

Approval steps are configured in the workflow editor. The following fields are set per approval step:

Field	Type	Required	Default	Description
action	string	Yes	—	What action is being requested
risk	enum	Yes	—	low | medium | high
slaMinutes	integer	Yes	—	Minutes before SLA breach
assignees	string[]	Yes	—	Email addresses of reviewers; must be workspace members

---

API endpoints

Method	Endpoint	Description
GET	/approvals	List all pending approvals in the workspace
GET	/approvals/{id}	Get a single approval request
PATCH	/approvals/{id}	Update an approval (e.g. reassign assignees)
POST	/approvals/{id}/approve	Approve the request (optionally with edited payload)
POST	/approvals/{id}/reject	Reject the request
POST	/approvals/{id}/comments	Add a comment to the approval thread
GET	/delegated-grants/{grantId}/approve	View a delegated grant
POST	/delegated-grants/{grantId}/approve	Approve a delegated grant
POST	/delegated-grants/{grantId}/deny	Deny a delegated grant

---

Examples

Deleting 500 customer records (risk: high)

An agent identifies 500 records marked for deletion as part of a data retention workflow. Before the deletion executes:

1. An approval step fires with risk: high, slaMinutes: 60
2. Evidence includes: { label: "Records identified", value: "500", tone: "amber" }, { label: "Retention policy match", value: "Yes", tone: "emerald" }
3. The data team lead reviews the record set in the payload, removes 3 records that should not be deleted, and approves with the edited payload
4. The deletion step runs against the reviewer-corrected record list

Sending a campaign email (risk: medium)

An agent drafts a promotional email for 12,000 recipients based on a segment definition.

1. An approval step fires with risk: medium, slaMinutes: 120
2. Evidence includes: { label: "Recipient count", value: "12,000", tone: "amber" }, { label: "Segment validation", value: "Passed", tone: "emerald" }
3. The marketing lead reviews the email draft in the payload, corrects one sentence, and approves
4. The notify step dispatches the approved draft

See /guides/human-in-the-loop-ai-agents for a detailed implementation guide.

---

Common mistakes

• Setting slaMinutes too short. If reviewers are in different timezones or work asynchronously, an SLA of 15 minutes will breach constantly. Set SLAs based on your team's actual response patterns.
• Not editing the payload when the agent's output is partially incorrect. The payload is editable before approving. Use this to correct errors rather than rejecting and re-running the entire workflow.
• Assigning approvals to a single person. If the sole assignee is unavailable, the SLA will breach. Use team distribution lists or multiple assignees for critical approval steps.
• Using risk: low for irreversible actions. Risk level influences how the approval is surfaced and prioritised. Use high for any action that is difficult or impossible to undo.

---

Troubleshooting

Run stuck in approval status — go to the Approvals page and find the pending approval for the run ID. Check that the assignees are correct and that they have received notifications. If the SLA has breached, reassign or approve directly.

Assignee not receiving notifications — verify that the assignee's email is correct and that they are an active workspace member. Check whether your workspace has a Slack or webhook notification channel configured — if SES delivery is failing, those channels may succeed.

Cannot edit payload — the payload field is editable only during the approval review, before the approve action is submitted. Once submitted, the payload is locked.

SFN task token error on resume — if the run fails to resume after approval with a the orchestration service error, the task token may have expired (SFN task tokens expire after 1 year). This is rare; contact support if it occurs.

---

Security and permissions

• editor and admin roles can approve and reject requests.
• viewer can view pending approvals but cannot action them.
• The encryptedTaskToken is encrypted with platform-managed keys and is never exposed in the UI or API responses.
• Audit events approval.granted, approval.rejected, approval.reassigned, and approval.sla_breach are emitted for each lifecycle event.
• grant.approved and grant.denied are emitted for delegated grant actions.
• Notifications are sent on approval_requested via email (SES), Slack, or webhook depending on workspace notification settings.

---

Related pages

• Workflows
• Workflow Runs
• Agents
• Getting Started

---

FAQ