Workflow Permissions New in 2
Audience:
Low-code Engineers,System/Security AdministratorsSkill Prerequisites:
Workflows,Roles
General Description
Workflow permissions decide which users can run each workflow, whatever runs it. A workflow can be restricted to some roles. After that, it runs only for users in one of those roles, whether it's started by a form, a listing, an API endpoint, a token, a guide, another workflow or an AI assistant.
The policy is set in one place and applied in one place:
- The roles are the app's roles, managed centrally on the Roles page. A workflow grants Execute to roles, never to single users. Adding a user to a role, or removing them, changes what they can run across every workflow that grants that role.
- The check happens in the workflow engine, before the first action runs. It doesn't depend on the form, API or page that calls the workflow, so no caller can skip it and no caller needs its own check.
- The permissions travel with the workflow. Export, import, clone and version control carry them to other apps and environments, so the same policy applies in development, test and production.
Without a restriction, a workflow behaves as before: anyone who can use the form, listing, API or page that runs it can run it.
Restricting a Workflow
- In App Builder › Workflows, open the workflow and select the Permissions tab, the last tab of the workflow editor.
- Turn on Restrict who can run this workflow.
- Check Execute for each role that should run the workflow.
- Select Save.
Changes on the Permissions tab are saved with the rest of the workflow. Leaving the workflow without saving them warns you, like any other unsaved change.
The Permissions Tab
| Part | What it shows |
|---|---|
| Restrict who can run this workflow | Off by default. When it's on, only the roles checked under Execute can run the workflow. |
| Hint, when off | Anyone who can use the form, listing, API or page that runs this workflow can run it. |
| Hint and warning, when on | Only roles with Execute can run this workflow. Scheduled jobs and test runs aren't checked., and in red: Anything that runs this workflow, such as forms, listings, APIs, guides or other workflows, will fail for users without one of these roles. |
| Role | Every role of the app. |
| Execute | Whether users in the role can run the workflow. It can be changed only while the workflow is restricted. |
| Read, Modify, Test | Who can see, edit and test the workflow in App Builder. These are always granted to Low-Code Engineers and above, and to no other role, and can't be changed for now. |
Turning the restriction off keeps the roles checked under Execute. Turning it back on applies them again.
Who Can Always Run a Workflow
These users always have every permission on every workflow, restricted or not:
- superusers;
- the site's Administrators role;
- the Low-Code Engineer and Admin roles.
Their checkboxes are always checked and can't be cleared. So a workflow restricted with no role checked under Execute can be run only by them.
To let anyone run a restricted workflow, including visitors who aren't signed in, grant Execute to All Users.
Where the Check Applies
The check applies to every way a workflow is run:
| Run by | Checked as |
|---|---|
| A form or a listing | The user who submits the form or uses the listing. |
| An API endpoint | The user the endpoint authenticates, for example with a JWT. |
| A token or a guide | The user who views the page or runs the guide. |
| Another workflow | The user the calling workflow runs as. A restricted workflow called from an unrestricted one is still checked. |
| An AI assistant, through the MCP server | The user who signed in the assistant. |
These runs are never checked:
- Scheduled jobs. A job has no user who called it.
- Test runs from App Builder, and every workflow a test run calls. Testing is governed by the Test permission.
- System workflows that come with the platform.
When a User Can't Run a Workflow
The run stops before any of the workflow's actions runs, so nothing is half done. The caller fails with an access denied error.
In a form, users see Access Denied. People who can administer the form, Low-Code Engineers and above on a standard site, see who was denied: Access Denied for user jsmith, or Access Denied for user Anonymous for a visitor who isn't signed in.
Moving Workflows Between Apps
Permissions are kept by role name when a workflow is exported, imported, cloned or pushed through version control:
- The workflow arrives restricted if it was restricted, and Execute is granted to the roles of the same names in the target app.
- A role that doesn't exist in the target app is left out, and a warning is written to the log. Create the role there, then check Execute for it on the workflow.
- An export made before workflow permissions existed carries none. Imported over an existing workflow, it leaves that workflow's restriction and roles as they are. Imported as a new workflow, it arrives not restricted.
Changes to Roles and Workflows
- Renaming a role keeps its grants in the app. Between apps, roles are matched by name, so give a role the same name in every app.
- Deleting a role removes it from every workflow's grants.
- Deleting a workflow deletes its permissions.
- Upgrading to a version with workflow permissions leaves every existing workflow not restricted, so it keeps running as before.
Example
The Send invoice workflow is run by a form, by an API endpoint used by the billing system, and by an AI assistant. Only Accounting should send invoices.
- Open Send invoice, select Permissions, turn on Restrict who can run this workflow, check Execute for Accounting and save.
- A user in Accounting submits the form, or asks the assistant to send an invoice: the workflow runs.
- A user who isn't in Accounting does the same: the form shows
Access Denied, and the assistant's tool call fails. No invoice is sent. - The monthly invoicing job still runs the workflow, since scheduled jobs aren't checked.
The form, the endpoint and the assistant didn't change: the policy is on the workflow, and every caller gets it.
Considerations
- Turning the restriction on can break callers. Forms, listings, APIs and other workflows that run the workflow fail for users without a granted role. Check which roles use them before restricting a workflow.
- Callers still have their own permissions. A form or a page can still be limited to some roles. Restricting the workflow adds a check; it doesn't replace theirs.
- Grant roles, not users. To change who can run a set of workflows, change who is in the role. See Roles.
- What callers other than forms show to a denied user, such as listings and APIs, is their usual error for a failed workflow.