Workflow Permissions

Overview

Workflow permissions control who can view, create, edit, and execute workflows in gaiia. Because workflows can automate actions at scale, permissions are restrictive by default to reduce the risk of unintended changes.

This article covers how workflow permissions are structured, what each permission allows a user to do, how to configure role-based and workflow-level access, and how to view the Activity Log.

Understanding how workflow permissions are scoped

Workflow permissions are applied at three levels:

Module-level permissions — control access to workflows as a feature (building, viewing, and executing workflows from the main launcher)
Object-level permissions — control access to workflows launched from specific object pages (Accounts, Commercial Accounts, Properties, Units)
Workflow-level permissions — further restrict, on a per-workflow basis, which specific users or groups (among those who already have edit or execute rights from their role) can edit or execute that workflow

Module-level and object-level permissions are configured in Settings > User Roles and apply to all users with that role. Workflow-level permissions are configured per-workflow and restrict access further within what a user's role already allows.

Managing module-level workflow permissions

Module-level permissions determine what actions a user can take within the Workflows module. These permissions are configured in Settings > User Roles under the Workflows section.

Edit

Create new workflows
Edit existing workflows
Run one-off executions using the Test button

Execution

Edit — execute workflows from the launcher, cancel ongoing workflows, and retry failed workflows
View — view workflow execution results, including inputs and outputs

Execution View access is required if Execution Edit is enabled.

Secrets

Edit — create and update workflow secrets, such as passwords and API keys
View — view workflow secrets without exposing sensitive values

Secrets View access is required if Secrets Edit is enabled.

Settings

Edit — create and update workflow variables
View — view existing workflow variables

Settings View access is required if Settings Edit is enabled.

View

View workflow definitions and workflow metadata

View access is required if any other Workflow permission is selected.

Managing object-level workflow permissions

Object-level permissions control who can run workflows from the workflow launcher on specific object pages. These permissions apply when users trigger workflows directly from Accounts, Commercial Accounts, Properties, or Units.

Object-level permissions are configured in Settings > User Roles under each object's permission section. They are independent from module-level permissions — a user might have Workflows > View but lack Accounts > Workflows > Launch, meaning they can browse workflow definitions but cannot execute workflows from an Account page.

Object-level permission tiers

Each object type has three permission tiers for workflows:

View — See the Workflows tab on the object page and view workflow execution history for that object
Launch — Start workflow executions from the object's workflow launcher
Edit — Retry failed executions and cancel running executions from the object page

View access is required if Launch or Edit is enabled for that object type.

Where to configure object-level permissions

Navigate to Settings > User Roles and select the role you want to modify. Object-level workflow permissions are located under each object module:

Accounts > Workflows — Available in the platform UI
Commercial Accounts > Workflows, Properties > Workflows, Units > Workflows — Contact your account team if you need these permissions enabled (currently configured through backend support)

When to use object-level permissions

Object-level permissions are useful when you want to allow users to execute workflows in specific contexts without granting broader module-level execution rights. Common scenarios:

Customer support representatives who launch account-specific workflows but should not access the workflow builder or execute workflows from the main launcher
Field service dispatchers who need visibility into workflow execution history on properties but should not trigger workflows themselves
Network operators who monitor automation status on accounts without execution rights

Understanding permission inheritance

Module-level and object-level workflow permissions use a parent-child inheritance model. When a parent permission is selected, all child permissions beneath it are automatically selected.

Child permissions cannot be enabled on their own and require the parent permission to be selected first.

For example, if you enable Workflows > Execution > Edit, the system automatically enables Workflows > Execution > View and Workflows > View.

Managing workflow-level access

In addition to module-level and object-level permissions, you can restrict who can edit and execute specific workflows. This is useful for protecting business-critical workflows from unauthorized changes or preventing sensitive workflows (like billing or provisioning) from being run by the wrong users.

Workflow-level access controls work alongside role-level permissions — they further restrict access, never expand it. For example, if a user doesn't have Workflows > Edit in their role, adding them to a workflow's edit access list won't grant them editing rights.

Access tiers

When you configure workflow-level access, you can assign users or user groups to one of two tiers:

Can edit — Edit workflow definitions, run test executions, publish new versions, and delete the workflow
Can execute — Launch the workflow from the launcher, retry failed executions, and cancel running executions. Users with execute-only access see a read-only view of the workflow definition and cannot see the Test button.

Set workflow-level access

Navigate to Workflows and open the workflow you want to restrict
Click the Access button (lock icon) in the workflow header
Select the access level you want to grant (Can edit or Can execute)
Search for a user by name or select a user group
Click Add

Users need the Workflows > Manage workflow access permission to configure workflow-level access. Users without this permission can view who has access but cannot modify it.

Lock icon states

The lock icon in the workflow header shows the current access state:

Unlocked — No workflow-level restrictions are configured. Access follows module-level and object-level permissions.
Locked — Access is restricted to specific users or user groups.

How workflow-level access works

Once you add users or groups to a workflow's access list, all other users are excluded from that permission tier. For example, if you add the "Account Managers" group to execute permissions, users who are not in that group will not be able to execute the workflow — even if their role grants them Workflows > Execution > Edit.

Users omitted from execute permissions:

Won't see the workflow in their launcher
Won't see the Test button in the workflow builder canvas
Can still view the workflow definition if they have Workflows > View

Users omitted from edit permissions:

See a read-only canvas with no edit controls
Cannot save drafts, publish, or delete the workflow

Role-level permissions remain a prerequisite:

Workflow-level access restricts beyond role permissions — it never expands them
If a user doesn't have base role permissions (like Workflows > Edit), adding them to a workflow's "Can edit" list won't grant them editing rights

Using user groups for workflow access

Instead of adding users individually, you can select an entire user group (like "Account Managers" or "Provisioning Team"). When someone joins or leaves the group, their workflow access updates automatically.

User groups are managed in Settings > User Groups. Once a group is created, it appears in the workflow Access dialog alongside individual users.

Remove workflow-level access

Open the Access dialog for the workflow
Find the user or group you want to remove
Click the X icon next to their name

The user or group no longer has workflow-level access. They may still be able to access the workflow if their role grants them the necessary module-level permissions.

Viewing the Activity Log

Every workflow has an Activity Log that tracks who created, published, modified permissions, or disabled the workflow. This provides a full audit trail across the workflow lifecycle.

Access the Activity Log

Open any workflow
Navigate to the Activity Log tab (next to Overview)
Review the timeline of events

Activity Log events

The Activity Log shows:

Workflow created — Who created the workflow and when
Version published — Version number, optional release notes, and the author
Access updated — Permission changes (who was added or removed, which access tiers were granted)
Workflow disabled/enabled — Status changes with timestamps

Each entry shows the event type, who performed the action, when it happened, and relevant details (like version notes or which users/groups were added or removed).

Note: The "Created by" and "Last updated" metadata that previously appeared at the top of the workflow builder has moved into the Activity Log.