Skip to main content

Managing Roles

Roles are the foundation of your RBAC system. This guide shows you how to create, modify, and manage roles effectively through the Workspace platform interface.

Understanding Roles​

A role is like a job title that bundles together specific permissions. Instead of assigning individual permissions to each user, you create roles and assign them to users who need those capabilities.

Role Characteristics​

  • Scoped to Resources: Roles apply to specific resource types (workspace, project, team, etc.)
  • Permission Collections: Each role contains multiple related permissions
  • Reusable: One role can be assigned to many users
  • Hierarchical: Some roles naturally build on others

Accessing Role Management​

  1. Navigate to Settings

    • Click your workspace name in the top navigation
    • Select "Settings" from the dropdown

  2. Open Roles & Permissions

    • Click "Roles & Permissions" in the settings sidebar
    • Select the "Roles" tab

Here you'll see all existing roles in your workspace, both default and custom.

Working with Default Roles​

The Workspace platform provides pre-configured roles to get you started:

Workspace Roles​

🔧 Workspace Admin​

Best for: IT administrators, founders, or senior managers

  • Complete workspace control
  • Manage all members and settings
  • Create and delete projects, teams, and billing accounts
  • Full role and permission management

👥 Workspace Manager​

Best for: Department heads, operations managers

  • Manage workspace settings and members
  • Create projects and teams
  • Invite new users
  • View billing information
  • Cannot delete workspace or manage billing accounts

👀 Workspace Viewer​

Best for: Stakeholders, executives who need visibility

  • View workspace details and members
  • See all projects and teams (but can't modify)
  • Read-only access across the workspace

Project Roles​

🚀 Project Admin​

Best for: Project managers, tech leads

  • Complete control over specific projects
  • Create workflows, bots, and knowledge bases
  • Deploy to production environments
  • Export project data

💻 Project Developer​

Best for: Software developers, automation builders

  • Create and modify workflows
  • Build and test bots
  • Update project configurations
  • Cannot deploy to production or export data

📖 Project Viewer​

Best for: Stakeholders, QA team, documentation reviewers

  • View project details and configurations
  • See workflows and bots (but can't modify)
  • Access project documentation

Team Roles​

👑 Team Lead​

Best for: Team managers, scrum masters

  • Manage team membership
  • Assign team-level roles
  • Configure team settings
  • Archive/reactivate teams

🤝 Team Member​

Best for: Regular team participants

  • View team details and members
  • Participate in team activities
  • Access team-specific resources

Creating Custom Roles​

When default roles don't fit your needs, create custom ones:

Step 1: Plan Your Role​

Before creating, consider:

  • Who needs this role? (job function, department, etc.)
  • What should they be able to do? (specific tasks and permissions)
  • What level does it apply to? (workspace, project, team)
  • How is it different from existing roles?

Step 2: Create the Role​

  1. Click "Create Role"

    • In the Roles tab, click the "Create Role" button

  2. Fill in Basic Details

    • Name: Use descriptive names like "Marketing Campaign Manager" or "External Consultant"
    • Description: Explain when and why to use this role
    • Resource Type: Choose what this role controls:
      • Workspace: For organization-wide roles
      • Project: For project-specific roles
      • Team: For team management roles
      • Other resource types: For specialized access

  3. Select Permissions

    • Browse available permissions by category
    • Basic Permissions: Read, Write, Update, Delete
    • Management Permissions: Create, Manage Members, Archive
    • Advanced Permissions: Deploy, Export, Execute, Manage Roles

  4. Use the Search Feature

    • Type keywords to find specific permissions
    • Example: Search "deploy" to find all deployment-related permissions

  5. Review and Save

    • Double-check your permission selections
    • Click "Create Role" to save

Example Custom Roles​

Marketing Manager​

  • Resource Type: Project
  • Permissions: Read, Update, Export (but not Delete or Deploy)
  • Use Case: Marketing team needs to manage campaigns but not affect production

External Consultant​

  • Resource Type: Project
  • Permissions: Read, Write (but not Deploy, Export, or Delete)
  • Time Limited: Set expiration dates on role assignments
  • Use Case: Temporary access for contractors and external collaborators

Finance Auditor​

  • Resource Type: Workspace
  • Permissions: Read, View Billing, View Reports (but no modification rights)
  • Use Case: Financial oversight without operational access

Modifying Existing Roles​

Editing Default Roles​

warning

Be Careful: Modifying default roles affects all users who have those roles. Consider creating custom roles instead.

  1. Select the Role

    • Click on the role name in the roles list
    • Or use the three-dot menu → "Edit Role"

  2. Modify Details

    • Update name or description if needed
    • Add or remove permissions by checking/unchecking boxes

  3. Save Changes

    • Click "Update Role"
    • Changes take effect immediately for all users with this role

Editing Custom Roles​

Custom roles can be freely modified:

  1. Access Role Details

    • Click the role name to open details
    • Or use "Edit Role" from the action menu

  2. Adjust Permissions

    • Add permissions as user needs evolve
    • Remove permissions that are no longer needed
    • Set expiration dates for temporary access

  3. Update Role Information

    • Revise name or description to reflect changes
    • Keep documentation current for other administrators

Role Best Practices​

Naming Conventions​

Good Role Names:

  • "Project Developer - Marketing"
  • "Team Lead - Engineering"
  • "External Consultant - Q1 2024"
  • "Finance Auditor"

Avoid These Names:

  • "John's Role"
  • "Temp Access"
  • "DevRole1"
  • "Admin2"

Permission Selection​

Start Conservative​

  • Begin with minimal permissions
  • Add more as users demonstrate need
  • It's easier to grant access than to revoke it
  • If someone needs "Read Project", they probably also need "Read Workflow"
  • Don't create roles with random, unrelated permissions

Consider Permission Inheritance​

  • Workspace permissions may affect projects within that workspace
  • Team permissions cascade to all team members
  • Plan for these inheritance patterns

Role Organization​

Use Categories​

Organize roles by:

  • Department: Marketing Roles, Engineering Roles, Finance Roles
  • Seniority: Junior Developer, Senior Developer, Principal Developer
  • Function: Project Management, Quality Assurance, Documentation

Document Role Purposes​

  • Always include clear descriptions
  • Note which job functions should use each role
  • Keep an organizational chart mapping roles to positions

Deleting Roles​

Before Deleting​

  • Check Usage: See which users currently have this role
  • Plan Migration: Decide which roles users should get instead
  • Communicate: Inform affected users about the change

Deletion Process​

  1. Identify Role Users

    • Click the role to see current assignments
    • Note all affected users

  2. Reassign Users

    • Move users to appropriate alternative roles
    • Or remove role assignments if no longer needed

  3. Delete the Role

    • Use the three-dot menu → "Delete Role"
    • Confirm the deletion
    • Warning: This action cannot be undone
danger

Important: Users lose access immediately when their roles are deleted. Always reassign users to appropriate roles before deletion.

Role Assignment Strategies​

Individual Assignment​

Best for:

  • Unique roles (like workspace admin)
  • Temporary access needs
  • Testing new role configurations

Team-Based Assignment​

Best for:

  • Large groups with similar needs
  • Consistent access patterns
  • Easier management at scale

Hybrid Approach​

Most organizations use both:

  • Team roles for common permissions
  • Individual roles for special access
  • Temporary individual roles for projects

Troubleshooting Role Issues​

Role Not Appearing for Assignment​

  • Check Resource Type: Ensure the role applies to the correct resource level
  • Verify Permissions: Make sure you have permission to assign this role
  • Refresh Browser: Sometimes a page refresh helps

Permissions Not Working as Expected​

  • Check Inheritance: Higher-level permissions might override role permissions
  • Verify Resource Scope: Ensure the role applies to the specific resource
  • Review Visibility Settings: Resource visibility is separate from permissions

Users Report Missing Access​

  • Confirm Role Assignment: Verify the user actually has the expected role
  • Check Role Contents: Ensure the role contains the necessary permissions
  • Test Role Yourself: Temporarily assign the role to test the permissions

Advanced Role Management​

Role Templates​

For organizations with multiple workspaces:

  • Create standard role templates
  • Apply consistently across workspaces
  • Maintain centralized role documentation

Role Auditing​

Regular role reviews:

  • Monthly check of role assignments
  • Quarterly review of role permissions
  • Annual assessment of role structure

Integration with Onboarding​

  • Create role assignment checklists for new hires
  • Standard role progressions for career advancement
  • Automated role assignments based on job titles

Next: Learn how to manage permissions within your roles, or explore user management to assign these roles to your team members.