Human approval steps

Approval & Human Tasks

Use this skill when building human approval gates, review tasks, manual input steps, and escalation timers inside workflows.

Tamper-Proof Approval Binding

1. Bind Every Approval Decision to the Exact Subject, Payload & Version:
   • When a workflow reaches an Approval step, snapshot the exact decision subject, frozen action parameters (payloadHash), runId, stepExecutionId, workflowVersionId, and expiresAt.
   • Record who decided (deciderUserId), in which workspace (tenantId), when (decidedAt), the decision (approved | rejected | changes_requested), and any reason/comment.
   • Never allow a workflow definition edit or post-request payload mutation to bypass or reuse an existing approval. If the underlying parameters change, the prior approval is invalidated.
2. Enforce Authorization & Separation of Duties (SoD) at Decision Time:
   • Verify on the server at the moment the human clicks "Approve" or "Reject":
     • The decider is an active member of the run's workspace (tenantId).
     • The decider currently holds the required role/permission or valid active delegation for that approval step and value threshold.
     • Self-Approval Prohibition: Unless explicitly exempted by a documented rule, the run initiator / requester cannot approve their own request (deciderUserId !== initiatorUserId).

Durable Expiration, Reminders & Multi-Approver Rules

• Explicit Quorum & Routing Rules:
  • Define whether a multi-approver step requires First Responder (1-of-N), Unanimous (All-of-N), or Sequential Chain (Manager -> Finance -> Legal) approval.
• Expiration & Escalation Timers:
  • Persist a durable expiresAt timer for every pending approval.
  • When now >= expiresAt, transition the approval atomically to expired (rejecting any late click with a clear conflict error) and route the workflow along its declared expired / escalation branch.
• Idempotent Decision Submission:
  • Guard the approval decision endpoint with atomic state transitions (WHERE status = 'pending') so double-clicking or two approvers acting simultaneously on a 1-of-N gate cannot advance the workflow twice.

Checklist

• Is the approval bound to runId, stepExecutionId, workflowVersionId, and a frozen payloadHash?
• Does the server verify workspace membership, permission, and self-approval prohibition (decider !== requester) at decision time?
• Are approval timeouts persisted as durable timers that route cleanly to an expired or escalation branch?
• Does atomic state checking prevent duplicate clicks from triggering double workflow resumption?