> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Role selection & management guide

> Practical guidance for selecting and assigning the right roles in FlowX Designer

> [!NOTE]
>
> **Documentation Navigation:**
>
> * [Workspaces Access Rights](https://docs.flowx.ai/6.x/setup-guides/access-management/workspaces-access-rights.md) - Role overview and concepts
> * [Complete Permissions Matrix](https://docs.flowx.ai/6.x/setup-guides/access-management/roles-permissions-matrix.md) - Detailed permission specifications
> * [Permission Reference Guide](https://docs.flowx.ai/6.x/setup-guides/access-management/permission-reference-guide.md) - Technical implementation details
> * **Role Selection Guide** (Current) - Practical scenarios and best practices

> [!NOTE]
>
> This guide helps you choose the appropriate roles for different users based on their responsibilities, expertise, and access requirements.

## Role selection decision tree

Use this decision tree to quickly identify the appropriate role:

```mermaid theme={"dark"}
graph TD
    A[Need to assign role] --> B{User manages multiple workspaces?}
    B -->|Yes| C[org_admin]
    B -->|No| D{User manages workspace resources?}
    D -->|Yes, full management| E[workspace_admin]
    D -->|No| F{What is user's primary responsibility?}
    F -->|Visual design & branding| G[theme_editor]
    F -->|Runtime deployments| H[workspace_runtime_editor]
    F -->|Process operations & migrations| N[workspace_operations_editor]
    F -->|Project configuration| I{Access level needed?}
    F -->|General workspace access| J[workspace_user]
    I -->|Full control & ownership| K[project_owner]
    I -->|Full configuration access| L[project_editor]
    I -->|View only for audit/review| M[project_viewer]
```

## Role selection by persona

### Platform administrators

> [card] Organization Administrator
>
> **Role:** `org_admin`
>
> **Typical Responsibilities:**
>
> * Managing the entire FlowX platform
> * Creating and organizing workspaces
> * Managing organization-wide users and groups
> * Overseeing system health and configurations
> * Implementing organization-wide policies
>
> **Example Users:**
>
> * Platform administrators
> * IT managers
> * System architects
>
> **Key Considerations:**
>
> * Assign sparingly - only to users needing cross-workspace access
> * Has access to ALL projects across ALL workspaces
> * Should be limited to 2-3 trusted individuals

### Business unit managers

> [card] Workspace Administrator
>
> **Role:** `workspace_admin`
>
> **Typical Responsibilities:**
>
> * Managing workspace users and access
> * Overseeing all workspace projects
> * Managing workspace themes and branding
> * Configuring workspace-level settings
> * Handling workspace resource allocation
>
> **Example Users:**
>
> * Department heads
> * Business unit managers
> * Team leads with administrative duties
>
> **Key Considerations:**
>
> * Has admin access to all projects in their workspace
> * Cannot access other workspaces without explicit assignment
> * Should be assigned to responsible leaders only

### Developers and configurators

> [card] Project Owner
>
> **Role:** `project_owner`
>
> **Assignment:** Automatic (assigned to project creator)
>
> **Typical Responsibilities:**
>
> * Complete project governance
> * Managing project team access
> * Final approval on project changes
> * Project lifecycle management
>
> **Example Users:**
>
> * Project leads
> * Technical architects
> * Product owners
>
> **Key Considerations:**
>
> * Automatically assigned at project creation
> * Can transfer ownership to another user
> * Only one owner per project

> [card] Project Editor
>
> **Role:** `project_editor`
>
> **Typical Responsibilities:**
>
> * Building and configuring processes
> * Designing workflows
> * Creating UI configurations
> * Managing integrations
> * Creating builds and deployments
>
> **Example Users:**
>
> * Senior developers
> * Business analysts
> * Technical configurators
>
> **Key Considerations:**
>
> * Full configuration access without ownership
> * Cannot grant/revoke project access
> * Standard role for project team members
>
> **Runtime Policy Access:**
>
> * Configurators who need to change active policy should be assigned `workspace_runtime_editor` role in their workspace
> * Even if they only have `project_viewer` access on specific projects, the workspace-level runtime role allows policy changes

### Specialized roles

> [card] UI/UX Designer
>
> **Role:** `theme_editor`
>
> **Typical Responsibilities:**
>
> * Designing application themes
> * Managing brand assets
> * Creating and organizing fonts
> * Managing media library
> * Ensuring visual consistency
>
> **Example Users:**
>
> * UI/UX designers
> * Brand managers
> * Visual designers
> * Marketing team members
>
> **Key Considerations:**
>
> * Extends workspace\_user with design permissions
> * Can create projects but focused on visual aspects
> * Read-only for projects without explicit access

> [card] DevOps Engineer
>
> **Role:** `workspace_runtime_editor`
>
> **Typical Responsibilities:**
>
> * Creating and managing builds
> * Configuring runtime environments
> * Managing deployment policies
> * Overriding configuration parameters
> * Monitoring process instances
>
> **Example Users:**
>
> * DevOps engineers
> * Release managers
> * Technical operations staff
> * System administrators
>
> **Key Considerations:**
>
> * Extends workspace\_user with runtime permissions
> * Can manage deployments across workspace
> * Does not grant automatic project configuration access

> [card] Operations Engineer
>
> **Role:** `workspace_operations_editor`
>
> **Typical Responsibilities:**
>
> * Managing process instance operations (migration & move token)
> * Editing process variables on active instances
> * Managing operational tasks across the workspace
> * Supporting process migrations and token movements
>
> **Example Users:**
>
> * Support engineers
> * Operations team members
> * Technical support staff
> * Process operations managers
>
> **Key Considerations:**
>
> * Extends workspace\_user with operations permissions
> * Can manage operations across workspace
> * Does not include broader runtime capabilities (builds, policies)

#### Operations Engineer role on SaaS

Assign the **Workspace corrective actions editor** role to Operations Engineers. It replaces the Workspace operations editor role, and existing assignments are moved to the new role automatically. The role lets users run migration and move token on process instances and edit process instance variables. See the [Workspace corrective actions editor permission matrix](https://docs.flowx.ai/6.x/setup-guides/access-management/roles-permissions-matrix.md#workspace-corrective-actions-editor-permission-matrix).

### Stakeholders and reviewers

> [card] General Workspace User
>
> **Role:** `workspace_user`
>
> **Typical Responsibilities:**
>
> * Creating new projects
> * Working on assigned projects
> * Viewing workspace resources
> * Basic workspace participation
>
> **Example Users:**
>
> * Junior developers
> * Business analysts
> * Process designers
> * General team members
>
> **Key Considerations:**
>
> * Default role for most workspace members
> * Can create projects (becomes owner automatically)
> * Needs explicit project access to work on others' projects

> [card] Viewer / Auditor
>
> **Role:** `project_viewer`
>
> **Typical Responsibilities:**
>
> * Reviewing project configurations
> * Auditing processes and workflows
> * Compliance checking
> * Documentation and training
>
> **Example Users:**
>
> * Business stakeholders
> * Quality assurance personnel
> * Compliance officers
> * External consultants
> * New team members (onboarding)
>
> **Key Considerations:**
>
> * Completely read-only access
> * Can test processes through interface
> * Safe for sensitive stakeholders

## Common role assignment scenarios

### Scenario 1: New employee onboarding

**1. Day 1: View-only access**

Assign `workspace_user` role at workspace level

Grant `project_viewer` role for relevant projects

**Rationale:** Allow new employee to explore and learn without risk

**2. Week 2-4: Limited editing**

Grant `project_editor` role for specific training projects

Keep viewer access for production projects

**Rationale:** Hands-on learning in safe environment

**3. After onboarding: Full access**

Grant `project_editor` role for assigned projects

Remove training project access

**Rationale:** Ready for production work with appropriate permissions

### Scenario 2: External consultant engagement

> [accordion] Short-term review (1-2 weeks)
>
> **Recommended Role:** `project_viewer`
>
> **Access Pattern:**
>
> * Grant access only to specific projects under review
> * No workspace-level role assignment
> * Time-bound access (remove after engagement)
>
> **Benefits:**
>
> * Complete visibility for review purposes
> * No risk of accidental modifications
> * Easy to audit consultant's activities

> [accordion] Implementation project (3-6 months)
>
> **Recommended Roles:**
>
> * Workspace level: `workspace_user`
> * Project level: `project_editor` for specific projects
>
> **Access Pattern:**
>
> * Create dedicated workspace for consultant projects
> * Grant editor access only to contracted projects
> * Regular access reviews during engagement
>
> **Benefits:**
>
> * Consultant can work independently
> * Clear boundaries on accessible projects
> * Easy cleanup after engagement ends

> [accordion] Long-term partnership (6+ months)
>
> **Recommended Roles:**
>
> * Workspace level: `workspace_user` or specialized role
> * Project level: `project_editor` or `project_owner` as needed
>
> **Access Pattern:**
>
> * Treat similar to internal team member
> * Consider dedicated workspace for partner projects
> * Quarterly access reviews and adjustments
>
> **Benefits:**
>
> * Full integration with team workflows
> * Appropriate access for extended engagement
> * Maintains security through regular reviews

### Scenario 3: Cross-functional team project

> [tab] Small Project (2-5 people)
>
> **Team Composition:**
>
> * 1 Project Owner (automatically assigned to creator)
> * 2-3 Project Editors (developers/analysts)
> * 1 Project Viewer (stakeholder)
>
> **Access Setup:**
>
> ```
> 1. Creator starts project → becomes project_owner
> 2. Grant project_editor to development team
> 3. Grant project_viewer to business stakeholder
> 4. Use "Everyone in workspace" group if all team members need access
> ```
>
> **Best Practices:**
>
> * Keep team small and roles simple
> * Regular sync meetings reduce need for complex permissions
> * Document decisions in project comments

> [tab] Medium Project (5-15 people)
>
> **Team Composition:**
>
> * 1 Project Owner (technical lead)
> * 5-8 Project Editors (developers, analysts, designers)
> * 1 Theme Editor (UI/UX specialist)
> * 2-3 Project Viewers (stakeholders, QA)
> * 1 Runtime Editor (DevOps)
>
> **Access Setup:**
>
> ```
> 1. Create workspace groups:
>    - "ProjectName_Developers" → project_editor
>    - "ProjectName_Stakeholders" → project_viewer
> 2. Assign specialized workspace roles as needed
> 3. Use groups for bulk permission management
> ```
>
> **Best Practices:**
>
> * Use groups instead of individual assignments
> * Regular access reviews (monthly)
> * Document group purposes clearly

> [tab] Large Project (15+ people)
>
> **Team Composition:**
>
> * 1 Project Owner (product owner/architect)
> * 10-15 Project Editors (multiple teams)
> * 2-3 Theme Editors (design team)
> * 1-2 Runtime Editors (DevOps team)
> * 5-8 Project Viewers (stakeholders, compliance, QA)
>
> **Access Setup:**
>
> ```
> 1. Create hierarchical groups:
>    - "ProjectName_Core_Team" → project_editor
>    - "ProjectName_Design_Team" → theme_editor + project_editor
>    - "ProjectName_DevOps_Team" → runtime_editor + project_editor
>    - "ProjectName_Stakeholders" → project_viewer
> 2. Use workspace admin to manage groups centrally
> 3. Implement approval workflow for access requests
> ```
>
> **Best Practices:**
>
> * Dedicated workspace admin for project
> * Automated access reviews (bi-weekly)
> * Clear escalation path for access issues
> * Document architecture decisions and ownership

### Scenario 4: Multi-workspace organization

> [card] Enterprise Organization Structure
>
> **Organizational Setup:**
>
> **Organization Level:**
>
> * 2-3 `org_admin` (Platform administrators)
>
> **Workspace Level (per business unit):**
>
> * 1 `workspace_admin` (Business unit manager)
> * 15-30 `workspace_user` (Standard members)
> * 2-3 `theme_editor` (Design team)
> * 1-2 `workspace_runtime_editor` (DevOps team)
> * 1-2 `workspace_operations_editor` (Operations/Support team)
>
> **Project Level (varies by project):**
>
> * Projects follow patterns from Scenario 3
>
> **Access Patterns:**
>
> * Each business unit has dedicated workspace
> * Cross-workspace collaboration via library sharing
> * Central DevOps team has runtime\_editor in all workspaces
> * Central design team has theme\_editor in relevant workspaces
> * Central operations team has operations\_editor for process management
>
> **Governance:**
>
> * Monthly access reviews by workspace\_admin
> * Quarterly organization-wide audit by org\_admin
> * Automated alerts for inactive users
> * Clear documentation of cross-workspace access

## Role escalation matrix

When should you upgrade a user's role?

| Current Role | Escalate To | Trigger Conditions | Approval Required |
| - | - | - | - |
| `project_viewer` | `project_editor` | User needs to make configuration changes Completed onboarding period | Project Owner |
| `workspace_user` | `theme_editor` | User assigned to design responsibilities Demonstrated design skills | Workspace Admin |
| `workspace_user` | `runtime_editor` | User assigned to DevOps responsibilities Deployment management needed | Workspace Admin |
| `workspace_user` | `operations_editor` | User assigned to operations responsibilities Process migration needs | Workspace Admin |
| `project_editor` | `project_owner` | Original owner leaving User taking over project leadership | Current Owner or Workspace Admin |
| `workspace_user` | `workspace_admin` | User promoted to management Administrative duties assigned | Organization Admin |
| `workspace_admin` | `org_admin` | User taking platform-wide responsibilities Multi-workspace management | Existing Org Admin + Management |

> [!WARNING]
>
> Always follow the principle of least privilege. Escalate roles only when necessary and document the business justification.

## Role de-escalation and removal

### When to downgrade roles

> [accordion] Project Completion
>
> **Scenario:** Project is completed and moved to maintenance
>
> **Action:**
>
> * Downgrade most `project_editor` to `project_viewer`
> * Keep 1-2 editors for maintenance
> * Keep project\_owner for governance
>
> **Timing:** At project completion milestone

> [accordion] Role Change
>
> **Scenario:** User moves to different team or responsibilities
>
> **Action:**
>
> * Remove access to old projects
> * Assign appropriate role for new responsibilities
> * Transfer project\_owner if applicable
>
> **Timing:** During role transition period

> [accordion] Contractor End
>
> **Scenario:** Contractor engagement ends
>
> **Action:**
>
> * Remove all workspace access
> * Document contractor's contributions
> * Archive or transfer project ownership if needed
>
> **Timing:** On contractor's last day

> [accordion] Security Incident
>
> **Scenario:** Suspicious activity or policy violation
>
> **Action:**
>
> * Immediate suspension of access
> * Investigation by security/admin team
> * Appropriate remediation based on findings
>
> **Timing:** Immediately upon detection

### Access removal checklist

**1. Identify all access points**

* List all workspaces user has access to
* Identify all projects with direct access
* Check group memberships
* Review project ownership assignments

**2. Transfer ownership**

* Transfer project\_owner role if user owns projects
* Update project documentation with new owner
* Notify project stakeholders of change

**3. Remove access**

* Remove from workspace-level roles
* Remove from project-level access
* Remove from all groups
* Verify removal in system

**4. Document and communicate**

* Document reason for removal
* Update team rosters and directories
* Communicate changes to affected teams
* Archive for compliance if needed

## Role assignment anti-patterns

> [!WARNING]
>
> Avoid these common mistakes when assigning roles:

### Anti-pattern 1: Everyone is an admin

**Problem:**

* Assigning `workspace_admin` or `org_admin` to too many users
* "Just in case" administrative access

**Impact:**

* Reduced security and accountability
* Increased risk of accidental changes
* Difficult to audit who made changes

**Solution:**

* Limit admin roles to actual administrators
* Use `project_editor` or `project_owner` for project-level needs
* Implement proper access request workflow

### Anti-pattern 2: Never updating roles

**Problem:**

* Roles assigned during onboarding never reviewed
* Users retain access after role changes
* Inactive users still have full access

**Impact:**

* Security vulnerabilities accumulate
* Compliance issues with access audits
* Potential data breaches

**Solution:**

* Quarterly access reviews
* Automated inactive user detection
* Role-based access recertification

### Anti-pattern 3: Individual assignments instead of groups

**Problem:**

* Assigning roles to individual users instead of groups
* Not using the "Everyone in workspace" group
* Managing access one user at a time

**Impact:**

* High administrative overhead
* Inconsistent access patterns
* Difficult to scale

**Solution:**

* Create groups for teams and functions
* Use groups for project access
* Individual assignments only for exceptions

### Anti-pattern 4: Too granular or too broad

**Problem:**

* Creating overly complex permission structures
* OR giving everyone the same high-level access

**Impact:**

* Confusion about who can do what
* Either too restrictive or too permissive
* Difficult to maintain

**Solution:**

* Start with predefined roles
* Use workspace/project boundaries naturally
* Add granularity only when truly needed

### Anti-pattern 5: No documentation

**Problem:**

* Access decisions not documented
* No record of why users have certain roles
* No clear ownership of access management

**Impact:**

* Cannot audit access decisions
* Difficult to troubleshoot access issues
* Compliance problems

**Solution:**

* Document all non-standard role assignments
* Maintain role assignment justifications
* Clear ownership of access management process

## Groups and access management

> [!NOTE]
>
> FlowX uses groups to simplify access management across users. Understanding built-in groups and creating custom groups efficiently manages permissions at scale.

### Built-in workspace groups

#### Everyone in workspace group

Every workspace automatically includes a special system-managed group for all workspace members:

> [card] all\_users\_\[workspace\_name]
>
> **Display Name in UI:** `Everyone from <workspace name>`
>
> **Purpose:**
> Provides convenient access management for all users associated with a workspace.
>
> **Automatic Behavior:**
>
> * Created automatically during workspace provisioning
> * Cannot be edited, deleted, or duplicated
> * Users automatically added when granted workspace access (direct or through another group)
> * Users automatically removed when workspace access is revoked
> * Pre-selected by default when creating new projects/libraries
> * Appears in user/group search results when granting project access
>
> **Common Use Cases:**
>
> * Grant all workspace members read access to reference projects
> * Provide baseline visibility across all workspace projects
> * Simplify onboarding by giving new users automatic access to shared resources
> * Create workspace-wide announcements or shared libraries
>
> **Example:**
>
> ```
> Workspace: "Product Development"
> Auto-created group: "all_users_product_development"
> Display name: "Everyone from Product Development"
> ```
>
> When creating a new project in "Product Development" workspace, the group "Everyone from Product Development" appears pre-selected, allowing immediate assignment of a role (viewer, editor, etc.) to all workspace members.

> [!WARNING]
>
> **Cannot Exclude Individual Members**
>
> The "Everyone in workspace" group includes ALL workspace members without exception. You cannot:
>
> * Remove specific users from this group
> * Create exceptions or exclusions
> * Modify group membership manually
>
> If you need selective access, create custom groups for specific teams or roles.

### Custom groups

> [tab] Creating Groups
>
> #### When to create custom groups
>
> Create custom groups when you need:
>
> * Team-based access (e.g., "Development Team", "QA Team")
> * Role-based access (e.g., "Senior Developers", "Stakeholders")
> * Project-specific access (e.g., "Project Alpha Team")
> * Cross-functional teams (e.g., "Release Management", "Architecture Board")
>
> #### Group creation best practices
>
> **1. Plan group structure**
>
> Identify natural team boundaries and access patterns before creating groups.
>
> **Good Examples:**
>
> * `dev_team_frontend`
> * `stakeholders_finance_dept`
> * `project_phoenix_core_team`
>
> **Poor Examples:**
>
> * `random_users`
> * `temp_group_1`
> * `johns_team` (too specific, not transferable)
>
> **2. Use descriptive names**
>
> Group names should clearly indicate purpose and membership.
>
> **Naming Convention:**
> `[function]_[department/project]_[sub-group]`
>
> **Examples:**
>
> * `developers_mobile_ios`
> * `viewers_executive_leadership`
> * `editors_project_migration`
>
> **3. Document group purpose**
>
> Add clear descriptions explaining:
>
> * Who should be members
> * What access the group provides
> * When to use the group for access grants
>
> **4. Assign appropriate permissions**
>
> Grant groups workspace-level roles, then use groups when assigning project access:
>
> ```
> 1. Create group: "Mobile Development Team"
> 2. Add members: All mobile developers
> 3. Grant workspace role: workspace_user
> 4. Use group for project access: Grant project_editor to "Mobile Development Team" on mobile projects
> ```

> [tab] Managing Groups
>
> #### Group lifecycle management
>
> **Adding Members:**
>
> * Add users individually
> * Bulk import from CSV
> * Integrate with identity provider groups (if configured)
>
> **Removing Members:**
>
> * Individual removal
> * Automatic removal when user leaves workspace
> * Bulk update operations
>
> **Modifying Groups:**
>
> * Update group name and description
>
> * Change group membership
>
> * Review and audit group access
>
> > [!WARNING]
> >
> > **Deleting Groups Impact**
> >
> > Deleting a group:
> >
> > * Removes all access granted through that group
> > * Does NOT delete the users themselves
> > * Cannot be undone
> > * May leave users without expected access
> >
> > Always verify group usage before deletion:
> >
> > 1. Check which projects use the group
> > 2. Identify affected users
> > 3. Plan alternative access methods
> > 4. Communicate changes to affected users

> [tab] Group Strategies
>
> #### Access patterns using groups
>
> **Pattern 1: Hierarchical Teams**
>
> ```
> all_users_product_development (workspace)
> ├── team_backend_developers
> ├── team_frontend_developers
> ├── team_qa_engineers
> └── team_product_owners
> ```
>
> Each sub-group receives different project roles based on responsibilities.
>
> **Pattern 2: Project-Based Groups**
>
> ```
> project_alpha_core_team → project_editor
> project_alpha_stakeholders → project_viewer
> project_alpha_devops → project_editor + workspace_runtime_editor
> project_alpha_operations → project_viewer + workspace_operations_editor
> ```
>
> Groups organized around specific projects for clear access boundaries.
>
> **Pattern 3: Cross-Functional Groups**
>
> ```
> architecture_review_board → project_viewer on all projects
> release_management_team → workspace_runtime_editor
> security_team → project_viewer + audit access
> ```
>
> Groups that span multiple projects with specialized access needs.
>
> **Pattern 4: External Collaboration**
>
> ```
> external_consultants_acme → project_editor on assigned projects only
> external_auditors_bigfour → project_viewer on compliance projects
> partners_vendor_xyz → project_viewer on integration projects
> ```
>
> Separate groups for external parties with time-bound access.

### Group vs. individual assignment decision matrix

| Scenario | Use Group | Use Individual Assignment |
| - | - | - |
| 5+ users need same access | ✅ Yes | ❌ No |
| Access pattern is temporary (\< 1 month) | ❌ No | ✅ Yes |
| Access follows team structure | ✅ Yes | ❌ No |
| One-off exception for specific user | ❌ No | ✅ Yes |
| Access will change frequently | ❌ No | ✅ Yes |
| Multiple projects need same team access | ✅ Yes | ❌ No |
| Executive/stakeholder with unique access | ❌ No | ✅ Yes |
| New team being formed | ✅ Yes | ❌ No |

## Troubleshooting permission issues

> [!NOTE]
>
> Common permission-related issues and their solutions. Use this guide to quickly diagnose and resolve access problems.

### Common error scenarios

> [accordion] Error: "Cannot see Projects menu"
>
> **Symptoms:**
>
> * Projects menu entry not visible
> * Workspace appears empty
> * Cannot navigate to any projects
>
> **Possible Causes:**
>
> 1. No workspace access granted
> 2. Missing `workspace_read` permission
> 3. Not a member of any workspace
>
> **Solutions:**
>
> **1. Verify workspace membership**
>
> Check if user has been granted access to the workspace:
>
> * Contact workspace administrator
> * Verify user appears in workspace Users list
> * Check group membership if access is group-based
>
> **2. Confirm workspace role**
>
> User needs at minimum `workspace_user` role:
>
> * Review user's assigned roles in workspace
> * Verify `workspace_read` permission is included
> * If missing, workspace admin should assign appropriate role
>
> **3. Clear cache and re-login**
>
> Sometimes permissions don't update immediately:
>
> * Log out of FlowX Designer
> * Clear browser cache
> * Log back in
> * Check if Projects menu now appears

> [accordion] Error: "Can see project but cannot edit"
>
> **Symptoms:**
>
> * Project appears in list
> * Can open project but all controls disabled
> * Configure shows as "View" instead
> * No Save buttons visible
>
> **Possible Causes:**
>
> 1. Have `project_viewer` role instead of `project_editor`
> 2. Have read-only permissions on project
> 3. Project is locked or archived
>
> **Solutions:**
>
> **1. Check project role**
>
> Verify assigned project role:
>
> * Open project
> * Look for edit controls (should be hidden if viewer)
> * Check contextual menu (Configure vs View)
>
> **2. Request role upgrade**
>
> Contact project owner to grant edit access:
>
> * Identify project owner (automatic creator or transferred owner)
> * Request `project_editor` role
> * Provide business justification for edit access
>
> **3. Verify project status**
>
> Ensure project is active:
>
> * Check if project is archived
> * Verify project version is editable
> * Confirm no system locks in place

> [accordion] Error: "Cannot create builds"
>
> **Symptoms:**
>
> * No "Create build" button visible
> * Import build action missing
> * Runtime menu entries not accessible
>
> **Possible Causes:**
>
> 1. Missing `wks_builds_create` permission
> 2. Don't have `workspace_runtime_editor` role
> 3. Workspace-level runtime access not granted
>
> **Solutions:**
>
> **1. Request runtime access**
>
> Contact workspace administrator:
>
> * Explain need for build creation
> * Request `workspace_runtime_editor` role
> * Alternative: Request specific `wks_builds_create` permission
>
> **2. Understand scope change**
>
> Note that runtime permissions moved to workspace level in v5.0:
>
> * Old: Per-project runtime access
> * New: Workspace-wide runtime access
> * May need different permission strategy

> [accordion] Error: "User added to group but still no access"
>
> **Symptoms:**
>
> * User appears in group membership list
> * User still cannot access expected resources
> * Group-based permissions not applying
>
> **Possible Causes:**
>
> 1. Group not assigned to project
> 2. Group has insufficient permissions
> 3. Permission cache not refreshed
> 4. Individual permission overrides group
>
> **Solutions:**
>
> **1. Verify group assignments**
>
> Check where group is used:
>
> * Check project-level access for group
> * Verify group has appropriate roles assigned
>
> **2. Check permission hierarchy**
>
> Understand permission precedence:
>
> * Individual permissions may override group
> * Multiple groups combine permissions
> * A user's permissions in the context of a project is the reunion of their permissions given though groups or individual assignments
>
> **3. Force refresh**
>
> Clear permission cache:
>
> * User logs out completely
> * Clear browser cache and cookies
> * User logs back in
> * Permissions should refresh from backend
>
> **4. Review group role**
>
> Ensure group has correct role:
>
> * Check group's workspace-level role
> * Verify group's project-level role
> * Confirm role includes needed permissions

> [accordion] Error: "Project owner left, cannot manage access"
>
> **Symptoms:**
>
> * Original project owner no longer with organization
> * Cannot grant/revoke project access
> * Project governance blocked
>
> **Possible Causes:**
>
> 1. Project ownership not transferred
> 2. No other users have admin rights on project
> 3. Workspace admin access not configured
>
> **Solutions:**
>
> **1. Contact workspace administrator**
>
> Workspace admin can help:
>
> * Has `projects_admin` permission
> * Can grant access to projects
> * Can help identify new owner
>
> **2. Transfer project ownership**
>
> Workspace admin or org admin can:
>
> * Assign new project owner
> * Transfer governance rights
> * Update project documentation
>
> **3. Prevent future issues**
>
> Implement ownership best practices:
>
> * Always have 2+ users with project\_editor minimum
> * Document ownership succession plan
> * Review project ownership quarterly
> * Assign workspace admin as backup owner for critical projects

## Best practices summary

> [card] Start Conservative
>
> Begin with `project_viewer` or `workspace_user` and escalate as needed based on demonstrated needs

> [card] Use Groups
>
> Create and use groups for teams and functions rather than managing individual user access

> [card] Regular Reviews
>
> Quarterly access reviews, remove inactive users, validate permissions match responsibilities

> [card] Document Decisions
>
> Maintain records of role assignments, especially for elevated privileges and exceptions

> [card] Use Automation
>
> Use group memberships and role inheritance to reduce manual access management

> [card] Plan for Transitions
>
> Have clear processes for role changes, project ownership transfers, and access removal

## Keycloak roles vs Designer roles

FlowX uses two separate role systems. Understanding the difference prevents common confusion:

| Aspect | Keycloak realm roles | FlowX Designer roles |
| - | - | - |
| **Managed in** | Keycloak Admin Console | FlowX Designer (Workspaces) |
| **Purpose** | Service authentication, runtime process access | Designer UI access, project permissions |
| **Assigned to** | Users and service accounts | Users and groups within workspaces |
| **Examples** | `SA_FLOWX`, `default-roles-flowx` | `org_admin`, `workspace_admin`, `project_editor` |

### Keycloak realm roles quick reference

| Role | Purpose | Who needs it |
| - | - | - |
| `SA_FLOWX` | Service account role. Identifies FlowX platform services for inter-service communication. | Service accounts only, not human users |
| `default-roles-flowx` | Default realm role automatically assigned to new users in the FlowX Keycloak realm. | All users (assigned automatically) |

> [!NOTE]
>
> In FlowX 4.x, roles like `FLOWX_ADMIN`, `FLOWX_CONFIGURATOR`, and `FLOWX_VIEWER` were Keycloak realm roles that controlled Designer access. In FlowX 5.0+, these have been replaced by the Designer role system (workspace\_admin, project\_editor, etc.). See the [legacy role migration](https://docs.flowx.ai/6.x/setup-guides/access-management/workspaces-access-rights.md#legacy-role-migration) for the full conversion table.

> [!WARNING]
>
> Do not confuse Keycloak realm roles with FlowX Designer roles. Assigning a user `workspace_admin` in Keycloak has no effect — it must be assigned through the FlowX Designer interface. Keycloak only handles authentication (login), while Designer handles authorization (what you can access).

***

## Related documentation

> [card] [Workspaces Access Rights](https://docs.flowx.ai/6.x/setup-guides/access-management/workspaces-access-rights.md)
>
> Overview of FlowX workspace access rights and role hierarchy

> [card] [Complete Permissions Matrix](https://docs.flowx.ai/6.x/setup-guides/access-management/roles-permissions-matrix.md)
>
> Detailed permission matrices for all FlowX roles

> [card] [Permission Reference Guide](https://docs.flowx.ai/6.x/setup-guides/access-management/permission-reference-guide.md)
>
> Technical implementation details, UI mappings, and naming conventions

> [card] [Access Management Overview](https://docs.flowx.ai/6.x/setup-guides/access-management/access-management-overview.md)
>
> Overview of FlowX access management system

> [card] [Configuring IAM Solution](https://docs.flowx.ai/6.x/setup-guides/access-management/configuring-an-iam-solution.md)
>
> Setting up identity and access management

> [card] [Workspaces](https://docs.flowx.ai/6.x/docs/projects/workspaces.md)
>
> Understanding workspaces and organizing projects


## Related topics

- [Workspaces access rights](https://docs.flowx.ai/6.x/setup-guides/access-management/workspaces-access-rights.md)
- [Complete roles & permissions matrix](https://docs.flowx.ai/6.x/setup-guides/access-management/roles-permissions-matrix.md)
- [Permission reference guide](https://docs.flowx.ai/6.x/setup-guides/access-management/permission-reference-guide.md)
- [FlowX.AI 5.1.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025.md)
- [End-user access management](https://docs.flowx.ai/6.x/setup-guides/access-management/end-user-access-management.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.