Role-based access control FAQs ​

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

Legacy collaborator roles continue to function normally until the deprecation date at the end of August 2026. Workato recommends that you complete your migration before this date to ensure uninterrupted access for all collaborators.

After August 31, 2026, you can no longer migrate your workspace yourself. Workato manages all remaining migrations and rolls them out by data center during the first two weeks of September 2026. Legacy roles continue to function throughout this period with no loss of permissions.

Workato sends you a report of all changes made to your workspace during the managed migration. The report includes the following information:

• The environment and project roles created from your existing roles
• The collaborator groups created from users who held the same role within an environment
• The collaborator group and project role assignments based on your previous project access

The behavior depends on your workspace structure:

• Automation HQ: Migrating inheritable roles in the Automation HQ workspace applies to every downstream workspace where the role is assigned. Downstream collaborator assignments update automatically. Custom collaborator roles created directly in a child workspace don't migrate automatically. Each child workspace admin must run the migration wizard in their workspace.
• Embedded: Migrating inheritable roles in the Embedded partner workspace applies to every customer workspace where the role is assigned, matching Automation HQ behavior. Custom roles created directly in a customer workspace don't migrate automatically. Migrate inheritable roles first, then migrate each customer workspace individually using the Embedded API or the in-app migration wizard. Refer to How do I migrate Embedded customer workspaces? in this section for more information.

Use the bulk-migration tool in Workspace admin > Access control > Collaborator roles. You must have Workspace admin access. The tool follows a two-step process:

• Generate and review a staged report that lists the new environment role each collaborator receives, the collaborator groups they join, and the project roles they hold for each project.
• Run the full migration. The wizard creates the new roles and collaborator groups and preserves equivalent access levels across your workspace.

Refer to the Migrate to the new access control model guide for step-by-step instructions.

Role attributes passed from your identity provider continue to manage environment access after migration. Project permissions can be managed in the Workato UI, or from your identity provider through the workato_user_groups attribute.

Configure the workato_user_groups attribute before the migration if you plan to manage project permissions from your identity provider. Refer to SAML role sync for configuration steps. No other action is required if you plan to manage project permissions in the UI.

Migrate inheritable roles in the Automation HQ workspace. The migration applies to every downstream workspace where the role is assigned, and downstream collaborator assignments update automatically.

Child workspaces that have their own custom collaborator roles must initiate a separate bulk migration independently. Each child workspace admin must run the migration wizard in their workspace to migrate locally created custom roles.

Migrate inheritable roles from the Embedded partner workspace first. The migration applies to every customer workspace where the role is assigned.

Then, migrate each customer workspace's remaining roles with the Embedded API:

• Use the POST /api/managed_users/:managed_user_id/roles_migration/system_roles endpoint to migrate a customer workspace's system roles.
• Use the POST /api/managed_users/:managed_user_id/roles_migration/custom_role endpoint to migrate a custom role from a customer workspace.

Set the dry_run parameter to true to preview the changes in a JSON response without migrating roles. The endpoints migrate one customer workspace at a time. You can create a recipe to repeat the process across customer workspaces.

Alternatively, you can run the in-app migration wizard in each customer workspace.

The migration splits each legacy collaborator role into a project role and an environment role and introduces collaborator groups. You may need to refactor your integration if your embedded UI displays or manages roles, or if your API calls create or assign collaborator roles. Contact your Customer Success Manager to align on a migration path and timeline if you expect a large impact on your customers.

Automation HQ provides central control over your organization's managed workspaces. Use it to represent business units as workspaces, share assets, control apps and limits, and create inheritable roles from the HQ workspace.

The Embedded Admin console is the central hub for Embedded partners to manage, monitor, and provision customer workspaces. You can access it from the navigation bar by selecting Manage customers or Admin > Manage customers.

Use Automation HQ if you manage workspaces for teams inside your organization. Use the Admin console if you are an Embedded partner managing workspaces created for your customers.

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.

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

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

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

Yes. Use the bulk-migration tool to consolidate and migrate all collaborator roles at scale. You can also use the Embedded or Developer API to migrate a role and create a recipe to repeat the process for other roles.

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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"

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.

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.

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.

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

HR developer, Marketing Admin

Group names are case-sensitive.

The platform defaults to the Member role if it detects a mismatch or missing context during SSO login. If you use the workato_role attribute to assign the Environment admin role, you must also include the workato_user_groups parameter.

Without workato_user_groups, the platform treats workato_role as a custom role. The system falls back to the default Member role if workato_role doesn't match any defined roles.

You can use the permissions model with the following steps:

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.

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.

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.

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

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.

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.

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.

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 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.

Yes. You can use the Embedded or 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. Refer to the following API documentation for additional information:

Developer API:

• Legacy roles: Manage roles that use the old permissions model.
• Role migration: Migrate roles from the old permissions model to the new model.
• Environment roles: Manage roles that control access at the environment level.
• Project roles: Manage roles that control access at the project level.
• Collaborator groups: Use groups to standardize and manage permissions for multiple collaborators at a time.
• Project grants: Manage project roles assignments.
• Workspace collaborators: Manage collaborators and their privileges.

Embedded API:

• Legacy roles: Manage roles that use the old permissions model.
• Role migration: Migrate roles from the old permissions model to the new model.
• Environment roles: Manage roles that control access at the environment level.
• Project roles: Manage roles that control access at the project level.
• Collaborator groups: Use groups to standardize and manage permissions for multiple collaborators at a time.
• Project grants: Manage project roles assignments.
• Customer workspace collaborators: Invite collaborators to a customer workspace.
• Manage customers: Manage customers and their workspace collaborators.

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.