Role Assignment
How users are assigned to roles and what happens when assignments change
Role Assignment
Role assignment connects users to their permissions within a company. Every company user has exactly one role assigned.
Assignment Model
The relationship between entities:
| Entity | Relationship | Description |
|---|---|---|
| User | 1:1 | Each user belongs to exactly one company |
| Company | 1:N | A company has multiple users and roles |
| CompanyUser | 1:1 | A company membership links to exactly one role |
| CompanyRole | 1:N | A role can be assigned to many users |
Assignment Rules
One Role Per User
Each user has exactly one role in their company:
A user belongs to one company and has one role within that company.
Role on Membership Creation
When a user is added to a company:
- A role must be selected during user creation
- Default is typically Member if auto-assigned
- Admins can select any active role
Users who self-register through company domains are automatically assigned the Member role.
Changing Role Assignments
Who Can Change Assignments
| Action | Required Permission |
|---|---|
| View user roles | Read Users |
| Change user role | Write Users |
How to Change a Role
- Navigate to Users in the dashboard
- Find the user to modify
- Click Edit to open the user form
- Select a different role from the Role dropdown
- Click Save Changes
When Changes Take Effect
Role changes are immediate:
- No need to log out and back in
- Next action uses new permissions
- Permissions are looked up fresh with each request
If you remove permissions a user is currently using, they may see errors on their next action. It's good practice to inform users before changing their access level.
Assignment Validation
Active Roles Only
Only active roles can be assigned:
| Role Status | Can Assign |
|---|---|
| Active | ✅ Yes |
| Inactive | ❌ No |
Existing Assignments Preserved
When a role is deactivated:
- Existing users keep their current assignment
- The role still functions for assigned users
- New users cannot be assigned to it
To fully remove a role's effect:
- Reassign all users to different roles
- Then deactivate or delete the role
Default Role Assignment
Self-Registration
When users self-register via domain verification:
| Scenario | Assigned Role |
|---|---|
| Email domain matches verified company | Member |
| Invited by admin | Role selected by admin |
| Manual creation | Role selected during creation |
After Predefined Role Initialization
When predefined roles are created for a company:
- Member, Manager, Admin roles are available
- New users default to Member unless specified
Bulk Role Assignment
For changing multiple users' roles:
- Navigate to Users
- Select multiple users (checkbox)
- Use Bulk Actions → Change Role
- Select the new role
- Confirm the change
Bulk assignment is only available if you have Write Users permission.
Audit Trail
Role assignment changes are logged:
| Event | Details Logged |
|---|---|
| Role assigned | User ID, Role ID, Assigned by, Timestamp |
| Role changed | Previous role, New role, Changed by, Timestamp |
| User removed from company | All role data, Removed by, Timestamp |
Access logs via:
- Dashboard audit log (if enabled)
- Backend event store
Best Practices
Review Assignments Periodically
- Check that users have appropriate roles for their current responsibilities
- Remove or downgrade access for users who have changed positions
- Audit high-privilege role assignments monthly
Document Role Purposes
Maintain clear documentation about:
- What each role is intended for
- Who should have each role
- When to upgrade or downgrade users
Use Least Privilege
When creating new users:
- Start with the minimum required role (typically Member)
- Upgrade to higher access only when needed
- Document the reason for elevated access