Role-based access control FAQs

Learn more about Workato's new permission model with these frequently asked questions.

Overview

What can I do with the permission model?

The new permission model enables the following capabilities:

• Project-level access control: Assign different roles per project within the same environment. Collaborators no longer share the same permissions across all projects in their environment.
• User group-based permissions: Grant project access to collaborator groups. Members inherit access automatically, making permission management scalable and consistent.
• Enhanced role lifecycle management: Use APIs and SAML/SCIM to manage roles and assignments programmatically.

How does the permissions model work with existing permissions?

The permissions model separates a collaborator's permissions into two types:

• Environment roles: Define permissions per environment. These roles govern platform settings, admin capabilities, and AHQ console access. Assign the necessary permissions in the Dev environment to access admin features or AHQ. Permissions in Test or Prod don't apply at the workspace level.
• Project roles: Define permissions within individual projects. These include access to folders, connections, recipes, deployments, and admin rights.

What system project roles are provided by default?

Workato provides four default project roles:

• Project operator: View-only access with recipe run and stop capabilities.
• Builder: Create recipes but can't deploy them.
• Advanced builder: Create and deploy recipes.
• Project admin: Full access to all project assets and settings.

You can also create unlimited custom roles with tailored permissions.

Prerequisites

What are the requirements before enabling the permission model?

The home assets (root) folder must be empty before you enable the model. You must store all assets within dedicated projects to meet the access control system requirement.

What happens if I have assets in the home assets folder?

You must migrate the assets into a project. Workato provides a migration script that performs the following actions:

• Converts Home Assets into a standard project in each environment.
• Retains the same folder_id and project_id.
• Enforces validation to block users from adding new assets to the root.

How do I migrate home assets?

Contact your Workato representative to confirm readiness. They run the migration script after confirmation. Complete this step before you enable the permission model.

Compatibility with the existing role model

What happens with collaborator roles when the permission model is enabled in my workspace?

The platform prevents users from creating new collaborator roles. It hides roles without assigned members in the UI but ensures that all roles remain accessible through the API. The platform assigns the role and displays it in the UI again when a user with that role logs in through SAML or SCIM.

Can I still access legacy roles through the API after migration?

Yes. The API provides full access to all roles, including legacy roles. You can retrieve the full list and assign legacy roles to collaborators using API endpoints. Roles without collaborators assigned to them are hidden in the UI.

What should early adopters do before enabling the permission model?

Create a complete record of all collaborator roles before you enable the permission model. Take screenshots or use the API to export the list. Some roles may disappear from the UI after migration.

Can old and new permission models work together during migration?

Yes. The platform supports both models at the same time. Some collaborators can use legacy roles while others use environment and project roles. Each collaborator must use one model per environment. The platform doesn't allow mixing legacy and new roles within a single environment.

Role migration process

What happens during role migration?

The migration prompts you to name the new environment and project roles. Both the environment and project roles use the name of the legacy collaborator role by default.

You can choose to:

• Add the Manage projects permission to the environment role.
• Add the Control project access permission to the project role.

The system generates an HTML summary report before the migration starts. It includes the following information:

• Number of collaborators assigned to the role
• List of new permissions
• Side-by-side comparison of current and updated permissions
• List of affected collaborators

The process then creates the new roles and automatically reassigns collaborators. All existing project access and permissions remain unchanged.

Can I preview changes before migrating a role?

Yes. The system provides a downloadable summary report that displays all changes before migration. This lets you review the updates without applying them.

What happens to collaborators assigned to a migrated role?

The system automatically reassigns these collaborators to the new project roles. Collaborators retain the same project access and receive equivalent permissions.

Can I migrate roles one at a time?

Yes. The migration process works on a role-by-role basis. You can migrate roles individually to support a gradual transition and testing.

Can I migrate multiple roles at once?

No. The system migrates roles one at a time. You can use the developer API to migrate a role and create a recipe to repeat the process for other roles.

How do I manage centralized permissions across multiple workspaces using Automation HQ?

Automation HQ supports inheritable environment and project roles:

• Admins in the parent workspace create roles based on the company's security policies.
• Child workspaces inherit these roles. Collaborators in child workspaces can use these role but can't modify them.
• Admins in the parent workspace prevent custom role creation when they exclude the Custom roles permission from child workspaces.

Collaborator groups

How do collaborator groups work with the permission model?

Collaborator groups are sets of collaborators that receive project roles as a unit. You must create a group and assign members before you can grant project access to the entire group instead of individuals.

What happens if a collaborator belongs to multiple groups?

The platform combines all permissions from the groups. The collaborator receives the highest level of access granted by any group. Permissions always increase with additional group memberships and never conflict or cancel each other.

How does session management work when group membership changes?

Group changes apply immediately after the page refreshes. Your identity provider reasserts group membership and overwrites any interim updates if the collaborator logs out and then back in through SAML or SCIM.

Project-access permissions

What is the Manage projects – Access control permission?

This environment-level permission allows administrators to perform the following actions:

• View the names of all projects in an environment, even without direct access.
• Add themselves to any project by selecting a role.
• Supervise project access across the workspace.

What is the Project administration – Access control permission?

This project-level permission allows collaborators to manage access control for a specific project. All collaborators with this permission have equal privileges and can modify each other's access within the project.

This permission supports delegated project-level administration. It doesn't allow users to invite new collaborators, create collaborator groups, or define new roles. It limits access control to existing users, groups, and roles within the project.

How does this admin access model differ from the old one?

The permission model introduces explicit access tracking and improves control:

• Old model: Admins had default read-only access to all projects. No logs captured when or where access occurred.
• New model: Admins can view all project names but must explicitly join a project to access it. The platform logs this action in the audit log.

This change improves visibility and restricts silent access to sensitive content such as finance or HR data.

System roles and system collaborator group

What system environment roles are provided by default?

The platform provides four default environment roles:

• No access: Blocks all access to the environment.
• Member: Grants minimal access without platform tool permissions or admin privileges.
• Environment manager: Grants full access to platform tools but excludes workspace admin privileges.
• Environment admin: Grants full access to all permissions in the environment.

What system project roles are provided by default?

The platform provides four default project roles:

• Project operator: Grants read-only access and the ability to run and stop recipes.
• Builder: Allows users to modify folders, recipes, Workato apps, and data tables. This role also allows test automation but not deployment.
• Advanced builder: Includes all builder permissions plus the ability to approve and deploy projects to other environments.
• Project admin: Grants full control over the project, including the ability to delete it.

Customers can create unlimited custom project roles to meet specific access needs.

How do I use the All collaborators system group for project access?

All projects deny access to the All collaborators group by default. A project admin can change this setting to assign baseline access to all collaborators who have environment access. This setup works well for shared projects that require general read access.

When should I use All collaborators instead of group assignment?

Use the All collaborators group to apply baseline access to everyone. Use specific groups when different teams need distinct access. Consider the following guidelines:

• All collaborators: Assign permissions that every user in the workspace should have, such as read access to shared resources.
• Group assignment: Assign access for teams that need specialized roles or responsibilities.

SAML and SCIM integration for role sync

What is the new SAML/SCIM parameter?

The SAML/SCIM parameter is workato_user_groups. It complements the following existing attributes:

• workato_role
• workato_role_test
• workato_role_prod

The platform applies the permission model with environment and project roles when it detects the workato_user_groups parameter during login. The system defaults to the legacy role assignment logic if the parameter is missing.

For example:

workato_role: "WorkspaceAdmin"
workato_role_test: "TestEnvAdmin"
workato_role_prod: "ProdEnvAdmin"
workato_user_groups: "HR developers, Marketing Admin"

What happens if a collaborator logs in through SAML or SCIM but the configuration isn't updated?

The platform assigns the collaborator a legacy role. SAML continues to act as the source of truth for role assignment. The system applies the following behavior if the workato_user_groups parameter is missing:

• Assigns legacy roles to collaborators during login.
• Keeps new environment and project roles visible to admins.
• Displays both role models in the system until SAML migration completes.

UI-ASSIGNED ROLES ARE REMOVED

The platform deletes UI-created role assignments the next time the collaborator logs in through SSO when the SAML configuration is active.

What happens when a SAML parameter includes a non-existent role?

The platform's behavior depends on the presence of the workato_user_groups parameter. It applies the following logic:

• If absent: The system uses the legacy model and assigns the default Operator role when the specified role doesn't exist.
• If present: The system uses the permission model and assigns the No access role when the specified role doesn't match any defined roles.

This behavior prevents excessive permissions caused by typos and helps admins detect configuration errors early.

CASE SENSITIVITY

The values in workato_user_groups are case-sensitive. For example, HR Developer and hr developer are treated as different groups.

What happens when a collaborator has an empty collaborator group value in SAML?

The platform assigns no project access to collaborators when workato_user_groups is empty. These users see an empty workspace with no accessible projects.

Admins can configure the All collaborators system group with default project access to ensure visibility for new users.

How do I assign multiple collaborator groups to a single collaborator in SAML?

Separate the values in the workato_user_groups attribute with commas. For example:

HR developer, Marketing Admin

Group names are case-sensitive.

Common use cases

How can I give production support access to specific projects only?

You can use the permissions model with the following steps:

1

Create collaborator groups for each support team, such as Finance App Support or HR App Support.

2

Define custom project roles with deployment and production support permissions.

3

Assign each group to their respective projects in the Prod environment.

4

Use environment roles to manage access to the Prod environment.

How can I enable teams to manage their own deployments without giving full workspace access?

You can assign project roles with deployment permissions only to the required projects. This configuration enables teams to do the following:

• Deploy their own recipes without IT intervention.
• Choose which recipes to deploy from their projects.
• Avoid modifying other teams' projects or shared services.
• Maintain deployment control within their team's scope.

How can I provide read-only access to sensitive projects for specific business units?

Create a collaborator group for the business unit and assign a custom Read Only project role to the required projects. This setup restricts access to specific content and prevents exposure to other projects or unnecessary permissions.

How do I handle collaborators who work across multiple teams or projects?

Assign the collaborator to multiple groups. The platform aggregates all permissions and grants the highest level from any group. For example:

• Member of marketing team: Assigned the Project operator role for the Marketing project.
• Member of advanced developers: Assigned the Advanced builder role for the Marketing project.

In this case, the collaborator receives the combined permissions from both roles for the Marketing project.

How can I set up shared projects that everyone can access?

Use the All collaborators group to assign baseline access. Apply the following configuration:

1

Open the project's Project access settings.

2

Set Everyone else in this environment to a base level such as Read Only.

3

Allow all collaborators with environment access to inherit this baseline permission.

4

Use group assignments to grant higher access to specific teams.

How do I prevent unauthorized access while delegating project management?

Use the Project administration – Access control permission to delegate project-level access management. Project owners can manage access only to their assigned projects. They can't invite new collaborators, create roles, or define new groups. Project owners can only assign existing roles and groups. The platform logs changes in the audit log.

How can I give a collaborator builder access in Dev/Test but read-only with deploy access in Prod?

Create two custom project roles to manage access across environments. Define a Power User role that grants full project access along with deploy permissions, including review, if enabled. Define a CI/CD Operator role that grants read-only access with deploy permissions.

Assign a basic environment role, such as a Member in all environments to provide minimal platform access.

Apply project roles per environment:

• Dev: Assign the Power User role.
• Test: Assign the CI/CD Operator role.
• Prod: Assign the CI/CD Operator role.

This configuration gives the collaborator full access in Dev, and read-only access with deploy permissions in both Test and Prod.

What happens if the target project doesn't exist in the destination environment during deployment?

The platform automatically creates the project if it doesn't exist, which can introduce a security risk:

• The collaborator must have the Create projects permission in their environment role.
• The collaborator receives Project admin access by default when the deployment creates a new project.

This overrides intended restrictions and grants full project-level permissions.

We recommend that an administrator with the Create projects permission create empty projects in Test and Prod, and assign the appropriate project roles such as CI/CD Operator before the first deployment.

How do deployment permissions work across environments?

Deployment permissions rely on project roles in both the source and target environments. A collaborator needs the following permissions to complete a deployment:

• Deploy permission in the source environment (Dev).
• Deploy permission in the target environment, such as Test or Prod.
• Create projects permission in the target environment to initialize the project during a first-time deployment.

This setup supports different deployment roles across environments and allows tighter access control.

API and automation

How do API keys work with the permission model?

API keys are environment-specific. You must use a separate API key for each environment (Dev, Test, Prod) to manage project access because permissions are tied to individual environments.

The platform handles API endpoints differently depending on what they access:

• Endpoints for collaborators and legacy collaborator roles work only in the Dev environment for backward compatibility.
• Endpoints for collaborator groups and environment/project roles return the same responses regardless of the environment.

Are there tools to help with bulk project permission management?

Yes. You can use developer API with the Workato app to build tools that simplify permission management. For example, you can select a source project and copy its project access matrix to multiple target projects.

Troubleshooting

A collaborator reports they lost access after SAML changes. What should I check?

Check the following in order:

• The SAML configuration includes the workato_user_groups parameter.
• The group names match exactly. These values are case-sensitive.
• The environment role names are correct in the workato_role, workato_role_test, and workato_role_prod parameters.
• The collaborator has logged in through SSO again after the configuration changes.