Approval steps

An approval step (called a Suspend step in the flow editor) pauses a flow run at a given step and waits for an external event — a click, a form submission, or an API call — before the flow continues. It’s the mechanism behind human-in-the-loop patterns: approve/reject gates, manual data entry mid-flow, and self-approved “prompt” steps.

Why approval steps?

Automation is powerful, but some operations are irreversible, high-risk, or require human judgement. An approval step gives you a safe checkpoint without breaking the automation flow:

• Deleting production data
• Sending bulk communications
• Deploying to a critical environment
• Initiating financial transactions
• Approving an AI agent’s proposed action (see AI agents)

How it works

A step suspends the flow by returning resume/cancel URLs as part of its own result — there’s no separate “approval node” type, any script or flow step can do this:

1. The step calls get_resume_urls() (Python) or getResumeUrls() (TypeScript, via @orvanta/client) and returns the URLs it gets back (typically as resume and cancel keys in its result).
2. Returning those URLs suspends the flow at that step. The job stays in the running state, but is flagged as suspended (job.suspend) — the runs UI surfaces this as “waiting for approval.”
3. Whoever holds a resume URL can approve by hitting it (GET or POST); hitting the cancel URL instead fails the step. Both URLs embed a per-job, per-resume secret, so no separate login is required to act on them unless you explicitly require one (see user_auth_required below).
4. If approved, the flow continues from the next step, with any payload posted to the resume URL available to it.
5. If cancelled, or if the step’s timeout is reached without enough approvals, the step (and by default the run) fails.

Configuring a suspend step

From the flow editor, select a step, open the Advanced menu, and go to the Suspend tab (the in-editor help calls this Suspend/Approval/Prompt). Available fields (backed by the flow’s Suspend config):

Field	Description
Number of approvals required (required_events)	How many distinct resume events are needed before the flow continues. Set to more than one to require multiple approvers.
Timeout (timeout)	Seconds to wait before the suspended step is considered timed out.
Form (resume_form)	A JSON schema the approver fills in when resuming, so the payload can carry more than a yes/no (Enterprise Edition only).
Require login to approve (user_auth_required)	If enabled, the resume/cancel URLs require the visitor to be authenticated.
Restrict to groups (user_groups_required)	Limit who can approve to specific workspace groups.
Disable self-approval (self_approval_disabled)	Prevents the user who triggered the run from also approving it.
Hide cancel button (hide_cancel)	Hides the cancel option in the approval UI.
Continue on disapprove/timeout (continue_on_disapprove_timeout)	Let the flow continue past the step instead of failing it when rejected or timed out.

Single vs. multiple approvers

If required_events is left at its default of one, the next step can read the payload back via a resume input. If you require more than one approval, use resumes instead to get an array of payloads, one per approver, and approvers to see who resumed it.

The “prompt” pattern

A prompt is just a suspend step that’s meant to be resumed by the same operator running the flow, rather than a separate approver — the runs UI shows it as an inline form instead of routing it to someone else. It’s useful for “pause here and let the operator fill in a value” steps, without needing a whole separate approval workflow.

Example step returning resume URLs

import orvanta

def main():
    urls = orvanta.get_resume_urls()
    return {
        "resume": urls["resume"],
        "cancel": urls["cancel"],
    }

Notifications

Orvanta doesn’t push approval notifications on its own — the suspending step gets plain URLs back from get_resume_urls(), and it’s up to that step’s code to deliver them wherever makes sense: post to Slack or Microsoft Teams (both have native app integrations for interactive approval messages), send an email via SMTP, or drop a message in whatever channel your team already watches.

Related

• Jobs and runs: Run lifecycle, including suspended jobs.
• Workflows: Step types and flow structure.
• AI agents: Gating an agent’s proposed action behind human review.