Roles & Permissions
Complete guide to roles, permission matrix, custom roles, and access control best practices.
Roles & Permissions
Understand and configure access control for your organization. AfricaOS uses role-based access control (RBAC) with five built-in roles and optional custom roles (Enterprise).
Who can manage roles?
Owner and Admin can assign roles. Only Owner can create custom roles (Enterprise). Go to Settings → Team → Roles.
Built-in role hierarchy
Owner (1 per org)
└── Admin
└── Manager
└── Staff
└── ViewerHigher roles inherit all permissions of lower roles. Only one Owner exists per organization.
Permission matrix
Organization level
| Action | Owner | Admin | Manager | Staff | Viewer |
|---|---|---|---|---|---|
| View organization details | ✓ | ✓ | ✓ | ✓ | ✓ |
| Edit organization profile | ✓ | ✓ | - | - | - |
| Manage branding | ✓ | ✓ | - | - | - |
| Manage localization | ✓ | ✓ | - | - | - |
| Manage billing & subscription | ✓ | ✓ | - | - | - |
| View invoices & usage | ✓ | ✓ | - | - | - |
| View audit log | ✓ | ✓ | - | - | - |
| Delete organization | ✓ | - | - | - | - |
Team management
| Action | Owner | Admin | Manager | Staff | Viewer |
|---|---|---|---|---|---|
| Invite users | ✓ | ✓ | - | - | - |
| Change roles | ✓ | ✓* | - | - | - |
| Suspend/activate users | ✓ | ✓ | - | - | - |
| Remove users | ✓ | ✓ | - | - | - |
| Manage module access | ✓ | ✓ | - | - | - |
| Manage workspace access | ✓ | ✓ | - | - | - |
*Admin cannot promote/demote Owner or other Admins
Module access (per installed module)
| Action | Owner | Admin | Manager | Staff | Viewer |
|---|---|---|---|---|---|
| Install/disable modules | ✓ | ✓ | - | - | - |
| Configure module settings | ✓ | ✓ | Assigned | - | - |
| Access assigned modules | ✓ | ✓ | ✓ | ✓ | Read-only |
| Create records | ✓ | ✓ | Assigned | Assigned | - |
| Edit records | ✓ | ✓ | Assigned | Assigned | - |
| Delete records | ✓ | ✓ | Assigned | - | - |
| Manage workflows | ✓ | ✓ | Assigned | - | - |
| Run reports/exports | ✓ | ✓ | Assigned | Assigned | Read-only |
*Assigned = module access set per user in Settings → Team → Edit user → Module access
Security
| Action | Owner | Admin | Manager | Staff | Viewer |
|---|---|---|---|---|---|
| Manage 2FA (org policy) | ✓ | ✓ | - | - | - |
| Manage SSO (WorkOS) | ✓ | - | - | - | - |
| Manage IP allowlist | ✓ | - | - | - | - |
| View session activity | ✓ | ✓ | - | - | - |
| Force logout users | ✓ | ✓ | - | - | - |
Module permissions detail
Each module has these permission levels:
| Level | Create | Read | Update | Delete | Configure |
|---|---|---|---|---|---|
| Full | ✓ | ✓ | ✓ | ✓ | ✓ |
| Write | ✓ | ✓ | ✓ | - | - |
| Read | - | ✓ | - | - | - |
| None | - | - | - | - | - |
Set per user: Settings → Team → Edit user → Module access
Workspace permissions
For organizations using workspaces (departments, locations, projects):
| Level | Description |
|---|---|
| Full | Manage workspace, all records, members |
| Write | Create/edit records in workspace |
| Read | View records in workspace |
| None | Workspace hidden |
Set per user: Settings → Team → Edit user → Workspace access
Custom roles (Enterprise)
Create tailored roles for specific job functions:
- Settings → Team → Roles → Create role
- Name and describe the role
- Select granular permissions from 100+ options
- Assign to users
Example custom roles
| Role | Modules | Permissions | Use case |
|---|---|---|---|
| Finance Manager | Payments, Finance | Full on billing, invoices, reports; Read on others | Handles all financial operations |
| HR Manager | HR, Staff, Patients | Full on staff records, leave, patients; Read on bookings | Manages people and scheduling |
| Inventory Clerk | Stock | Full on stock, suppliers, orders; Read on payments | Daily warehouse operations |
| Receptionist | Bookings, Patients | Full on bookings; Read on patients; Schedule only | Front desk scheduling |
| Compliance Officer | All | Read on all; Audit log access; Export only | Compliance and auditing |
| Sales Rep | Payments, Bookings | Write on invoices, bookings; Read on patients | Customer-facing sales |
Creating a custom role
- Go to Settings → Team → Roles
- Click Create custom role
- Enter name (e.g., "Finance Manager") and description
- Copy from - Start from an existing role (Admin, Manager, etc.)
- Toggle permissions on/off per category
- Click Create
- Assign to users in Settings → Team
Best practices
Principle of least privilege
Give minimum access needed. Start with Viewer, add permissions only when required.
Use roles, not individual perms
Assign roles consistently. Avoid one-off permission grants - create a custom role instead.
Quarterly access reviews
Audit who has what access every quarter. Remove access for departed or changed roles.
Separation of duties
No single user should control billing + approve payments + manage users. Split across roles.
Document custom roles
Keep a living document of each custom role purpose, permissions, and who holds it.
Test before assigning
Create a test user, assign the role, verify access matches expectations.
Common patterns
Healthcare clinic
- Owner - Practice owner
- Admin - Office manager
- Manager - Lead physician, head nurse
- Staff - Physicians, nurses, medical assistants
- Viewer - Billing partner, auditors
Retail chain
- Owner - Business owner
- Admin - Regional managers
- Manager - Store managers
- Staff - Sales associates, stock clerks
- Custom: Inventory Clerk - Stock only
Professional services
- Owner - Managing partner
- Admin - Operations director
- Manager - Practice leads
- Staff - Consultants, associates
- Custom: Finance Manager - Billing only
Troubleshooting
| Issue | Likely cause | Fix |
|---|---|---|
| User sees module but cannot edit | Module access set to "Read" | Change to "Write" or "Full" |
| User cannot see module at all | Module access set to "None" | Assign appropriate level |
| Admin cannot demote another Admin | Admins cannot manage other Admins | Owner must do it |
| Custom role not appearing | Enterprise feature not enabled | Check plan or contact support |