User Roles and Permissions
Role Hierarchy
The Membership platform defines six hierarchical role levels, three vendor-level roles, and five specialized lateral roles. Each higher-level role inherits all permissions of the levels below it. Two additional special-purpose roles (Trainer/Coach and Parent/Guardian) operate outside the primary hierarchy with their own scoped permissions.
Role Definitions
Vendor Tier: Vendor Admin
The top-level platform operator role for Membership One staff. Vendor Admins have unrestricted cross-tenant access for platform management, customer onboarding, and incident response. This role supersedes System Admin with the added ability to manage the platform's own B2B operations (sales pipeline, customer health, SaaS billing).
Scope: All tenants, all data. Platform configuration, tenant provisioning, customer lifecycle management, system monitoring, user impersonation for support.
Authentication: Corporate SSO with mandatory MFA. Access logging to immutable audit trail.
Vendor Tier: Vendor Support Agent
A scoped cross-tenant role for Membership One support staff. Support agents can view customer data and impersonate users for troubleshooting, but cannot modify platform configuration, pricing, or tenant settings. All actions are logged.
Scope: Read access across all tenants. Can view member data, transactions, and configurations. Can create internal notes. Cannot modify tenant data directly — must escalate to Vendor Admin for changes.
Vendor Tier: Vendor Sales
A scoped cross-tenant role for Membership One sales staff. Sales agents manage the B2B pipeline: prospects, demos, proposals, and customer onboarding. They can view tenant health metrics but cannot access individual member data.
Scope: CRM pipeline (leads, deals, activities). Tenant overview (health scores, usage metrics, contract status). Cannot access member PII or financial transaction details.
Level 1: Member
The base-level role for all registered consumers. Members interact with the system exclusively through the mobile app or member web portal. They manage their own profile, view their contracts and payments, perform check-ins, and book resources.
Scope: Own data only. Cannot see other members' data. Cannot access any admin functionality.
Authentication: Email/password via MbLogin, with email verification and optional two-factor authentication.
Level 2: Team Leader / Captain
An elevated member role for individuals who lead a team, department, or group within an organization. Team leaders can view their team roster, manage attendance, and send communications to team members. They cannot modify organizational settings, contracts, or billing.
Scope: Own data plus read access to assigned team members' basic profiles and attendance records.
Level 3: Club / Studio Admin
The primary administrator for a single organization (club, studio, school, gym). This is the most common admin role. Club admins have full control over their organization: member management, contract creation, billing, resource configuration, event planning, communication, and settings. They cannot access data from other organizations or modify platform-level settings.
Scope: All data within their organization (filtered by idMcEntity). Full CRUD on members, contracts, billing, resources, events, communication, and settings for that organization.
Level 4: Group Admin
Manages a regional group or umbrella association that contains multiple organizations. A group admin can view aggregated data across child entities, enforce policies (e.g., standardized contract templates, shared branding), and manage cross-organization features (shared memberships, inter-club access). They can also act as a club admin within any child organization.
Scope: All data within their entity and all child entities in the hierarchy. Can create and manage child organizations.
Level 5: Franchisor Admin
Manages a franchise network. Has all group admin capabilities plus franchise-specific features: brand enforcement across all franchisees, standardized product catalogs, centralized reporting, and financial consolidation. Can provision new franchise locations and control which features and settings franchisees can customize.
Scope: Entire franchise network (root entity and all descendants). Can override settings and enforce templates across all organizations in the network.
Level 6: System Admin
Platform operator with unrestricted access. Manages tenant provisioning, platform configuration, system health, and can impersonate any other role for support purposes. System admins do not belong to a specific organization -- they operate at the platform level.
Scope: All data across all tenants. Platform configuration, user impersonation, system monitoring, database management.
Special Role: Trainer / Coach
Assigned by a club admin to individuals who lead classes, training sessions, or courses. Trainers see their class schedule, manage attendance, communicate with participants, and track performance. Sub-roles distinguish between different trainer types: fitness instructor, sports coach, physiotherapist, course leader.
Scope: Classes and courses they are assigned to. Participant lists for their sessions. Cannot modify contracts, billing, or organizational settings.
Special Role: Parent / Guardian
Linked to a minor member's account. Parents can view and manage the minor's profile, contracts, payments, and attendance. They receive all notifications intended for the minor. A parent can be linked to multiple minors and can also hold their own member account simultaneously.
Scope: Full access to linked minor's data. Receives minor's notifications. Can manage minor's contracts and payments.
Specialized Role: Finance Admin
Manages the accounting function for a club or franchise network. Has full access to financial operations including general ledger, DATEV export, bank reconciliation, and expense management. This role is parallel to Club Admin — a Finance Admin cannot manage members or resources but has deeper financial access than a Club Admin.
Scope: All financial data within their organization (or network for franchise-level): general ledger, transactions, invoices, bank accounts, cost centers, expenses, budgets, DATEV exports, financial reports. Cannot modify member profiles, contracts, resources, or events.
Specialized Role: Sales / Marketing Admin
Manages the CRM and marketing function. Has full access to lead management, pipeline, deal tracking, campaigns, and conversion analytics. Can view member data needed for sales context but cannot modify contracts or financial records.
Scope: CRM data (leads, deals, activities), marketing campaigns, lead source analytics, trial management, referral programs. Read-only access to member profiles and contract status for sales context.
Specialized Role: Support Agent
Handles member support tickets, knowledge base management, and communication within their organization. Can view member profiles and transaction history for support context but cannot modify financial or contractual data.
Scope: Tickets (CRUD), knowledge base articles (CRUD), member profiles (read-only for support context), communication tools. Cannot modify contracts, billing, or organizational settings.
Specialized Role: Operations Manager
Manages physical operations: resource utilization, maintenance, staffing, and facility compliance. Can view member data only for operational context (check-in patterns, resource usage). Cannot access financial or contractual data.
Scope: Resources (CRUD), maintenance scheduling, equipment inventory, staff scheduling, facility compliance checklists. Read-only access to check-in data and occupancy metrics.
Specialized Role: Access Control Admin
Configures and manages physical access control infrastructure: zones, credentials, hardware, and access rules. A specialized technical role that requires understanding of hardware systems (Gantner, OSDP, BLE).
Scope: Access zones (CRUD), credentials (CRUD), access rules (CRUD), hardware configuration, door commands (lock/unlock/override), access logs, occupancy monitoring. Cannot modify member profiles, contracts, or financial data.
Permission Matrix
The following matrix defines permissions per role across all functional modules. Permissions are: Create, Read, Update, Delete, Approve, Export. A dash (--) indicates no access.
Member and Organization Management
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Trainer | Parent |
|---|---|---|---|---|---|---|---|---|
| Own profile | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD |
| Other member profiles | -- | R (team) | CRUD | CRUD | CRUD | CRUD | R (class) | R (minor) |
| Member search | -- | R (team) | R | R | R | R | R (class) | -- |
| Member import/export | -- | -- | CRE | CRE | CRE | CRE | -- | -- |
| Organization settings | -- | -- | RU | RU | CRUD | CRUD | -- | -- |
| Child organizations | -- | -- | R | CRUD | CRUD | CRUD | -- | -- |
| Custom attributes | RU (own) | RU (own) | CRUD | CRUD | CRUD | CRUD | R | RU (minor) |
Membership and Contracts
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Trainer | Parent |
|---|---|---|---|---|---|---|---|---|
| View own contracts | R | R | R | R | R | R | R | R (minor) |
| Purchase membership | C | C | -- | -- | -- | -- | C | C (minor) |
| Contract templates | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Assign contracts | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Cancel/suspend contracts | R (request) | R (request) | CRUA | CRUA | CRUA | CRUA | -- | R (minor) |
| Pricing and discounts | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Contract reports | -- | -- | RE | RE | RE | RE | -- | -- |
Financial Operations
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Trainer | Parent |
|---|---|---|---|---|---|---|---|---|
| Own transactions | R | R | R | R | R | R | R | R (minor) |
| All transactions | -- | -- | RE | RE | RE | RE | -- | -- |
| Create manual transaction | -- | -- | C | C | C | C | -- | -- |
| Billing cycles | -- | -- | CRA | CRA | CRA | CRA | -- | -- |
| SEPA exports | -- | -- | CRE | CRE | CRE | CRE | -- | -- |
| Bank accounts (own) | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD (minor) |
| Bank accounts (org) | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Bookkeeping export | -- | -- | RE | RE | RE | RE | -- | -- |
| Refunds | -- | -- | CA | CA | CA | CA | -- | -- |
Resource Management
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Trainer | Parent |
|---|---|---|---|---|---|---|---|---|
| View resources | R | R | R | R | R | R | R | R |
| Book resources | C | C | CRUD | CRUD | CRUD | CRUD | C | C (minor) |
| Manage resources | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Equipment issue/return | R (own) | R (team) | CRUD | CRUD | CRUD | CRUD | CRU (class) | -- |
| Access control config | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Utilization reports | -- | -- | RE | RE | RE | RE | -- | -- |
| Approve bookings | -- | -- | A | A | A | A | -- | -- |
Events and Courses
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Trainer | Parent |
|---|---|---|---|---|---|---|---|---|
| View events/courses | R | R | R | R | R | R | R | R |
| Register for events | C | C | CRUD | CRUD | CRUD | CRUD | C | C (minor) |
| Create/manage events | -- | -- | CRUD | CRUD | CRUD | CRUD | CRU (own) | -- |
| Manage attendance | -- | RU (team) | CRUD | CRUD | CRUD | CRUD | CRU (own) | -- |
| Trainer assignment | -- | -- | CRUD | CRUD | CRUD | CRUD | R | -- |
| Tournament management | -- | R | CRUD | CRUD | CRUD | CRUD | CRU (own) | -- |
Communication
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Trainer | Parent |
|---|---|---|---|---|---|---|---|---|
| Receive notifications | R | R | R | R | R | R | R | R |
| Send to team/class | -- | C (team) | C | C | C | C | C (class) | -- |
| Email templates | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Newsletter campaigns | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Landing pages | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Push notification config | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
Platform Administration
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Trainer | Parent |
|---|---|---|---|---|---|---|---|---|
| User management | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| Role assignment | -- | -- | CRU (below own) | CRU (below own) | CRU (below own) | CRUD | -- | -- |
| Audit logs | -- | -- | R (own org) | R (group) | R (network) | R (all) | -- | -- |
| System configuration | -- | -- | -- | -- | -- | CRUD | -- | -- |
| Tenant provisioning | -- | -- | -- | -- | C (franchise) | CRUD | -- | -- |
| Data export (GDPR) | R (own) | R (own) | RE | RE | RE | RE | R (own) | R (minor) |
| API key management | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
CRM and Sales
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Vendor Admin | Sales/Mktg Admin | Vendor Sales |
|---|---|---|---|---|---|---|---|---|---|
| View leads | -- | -- | R | R | R | R | R | R | R |
| Create/edit leads | -- | -- | CRU | CRU | CRU | CRU | CRUD | CRUD | CRUD |
| Delete leads | -- | -- | -- | D | D | D | D | D | D |
| Pipeline configuration | -- | -- | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | -- |
| Deal management | -- | -- | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD |
| Activity logging | -- | -- | CRU | CRU | CRU | CRU | CRUD | CRUD | CRUD |
| CRM reports | -- | -- | RE | RE | RE | RE | RE | RE | RE |
| Trial management | -- | -- | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | R |
| B2B account management | -- | -- | -- | -- | -- | R | CRUD | -- | CRUD |
Support and Ticketing
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Vendor Admin | Support Agent | Vendor Support |
|---|---|---|---|---|---|---|---|---|---|
| Create ticket | C | C | C | C | C | C | C | C | C |
| View own tickets | R | R | R | R | R | R | R | R | R |
| View all tickets | -- | -- | R | R | R | R | R (all tenants) | R (own org) | R (all tenants) |
| Update tickets | -- | -- | CRU | CRU | CRU | CRU | CRUD | CRU | CRU |
| Delete tickets | -- | -- | -- | D | D | D | D | -- | -- |
| Assign tickets | -- | -- | CRU | CRU | CRU | CRU | CRUD | CRU | CRU |
| KB articles | -- | -- | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD |
| SLA configuration | -- | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
| CSAT reports | -- | -- | R | RE | RE | RE | RE | R | RE |
| Escalation config | -- | -- | -- | CRUD | CRUD | CRUD | CRUD | -- | -- |
Accounting and DATEV
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Vendor Admin | Finance Admin |
|---|---|---|---|---|---|---|---|---|
| View ledger | -- | -- | R | R | R | R | R | R |
| Create journal entries | -- | -- | -- | -- | -- | C | C | CRUD |
| Approve postings | -- | -- | -- | A | A | A | A | A |
| Cost centers | -- | -- | R | R | R | CRUD | CRUD | CRUD |
| DATEV export | -- | -- | -- | E | E | E | E | RE |
| Bank reconciliation | -- | -- | -- | -- | -- | RU | RU | CRUD |
| Expense management | -- | -- | CRU | CRU | CRU | CRUD | CRUD | CRUD |
| Budget management | -- | -- | R | RU | RU | CRUD | CRUD | CRUD |
| Financial reports | -- | -- | R | RE | RE | RE | RE | RE |
Executive Dashboards
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Vendor Admin | Finance Admin | Ops Manager |
|---|---|---|---|---|---|---|---|---|---|
| View club dashboard | -- | -- | R | R | R | R | R | R | R |
| View network dashboard | -- | -- | -- | R | R | R | R | R | -- |
| View vendor dashboard | -- | -- | -- | -- | -- | R | R | -- | -- |
| Configure widgets | -- | -- | RU | RU | RU | CRUD | CRUD | RU | RU |
| Export dashboard | -- | -- | E | E | E | E | E | E | E |
| Alert configuration | -- | -- | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD |
| Scheduled reports | -- | -- | CRUD | CRUD | CRUD | CRUD | CRUD | CRUD | -- |
Access Control
| Permission | Member | Team Leader | Club Admin | Group Admin | Franchisor | System Admin | Vendor Admin | Access Ctrl Admin | Ops Manager |
|---|---|---|---|---|---|---|---|---|---|
| View own credentials | R | R | R | R | R | R | R | R | R |
| Zone management | -- | -- | R | R | R | CRUD | CRUD | CRUD | R |
| Credential management | -- | -- | CRU | CRU | CRU | CRUD | CRUD | CRUD | -- |
| Access rule config | -- | -- | RU | CRUD | CRUD | CRUD | CRUD | CRUD | -- |
| Override denial | -- | -- | C | C | C | C | C | C | C |
| Hardware config | -- | -- | -- | -- | -- | CRUD | CRUD | CRUD | -- |
| Door commands | -- | -- | C | C | C | C | C | C | C |
| Access logs | R (own) | R (team) | RE | RE | RE | RE | RE (all) | RE | RE |
| Occupancy monitoring | R | R | R | R | R | R | R | R | R |
Frontend Strategy: Single App with Role-Based Views
Recommendation: Deploy a single Flutter application with role-based view rendering rather than separate apps per role.
Rationale
| Factor | Single App (recommended) | Separate Apps |
|---|---|---|
| Codebase maintenance | One codebase, shared components | 3-4 codebases with duplication |
| App store presence | One listing, one review process | Multiple listings, multiple reviews |
| User experience | Role switcher, seamless transitions | App switching, separate logins |
| Brand consistency | Guaranteed consistent | Risk of drift |
| Deployment complexity | One build pipeline | Multiple pipelines |
| Update synchronization | Automatic | Must coordinate releases |
| Storage on device | One app installation | Multiple installations |
| Development cost | Lower (shared 70-80% of code) | Higher (duplicated effort) |
Implementation Approach
The app determines the user's role(s) at login from the JWT token claims. The router, navigation structure, and available screens adapt based on the role:
- Member: Bottom navigation (Memberships, Access, Payments, Profile). No admin screens visible.
- Trainer: Bottom navigation adds Schedule and Attendance tabs. Class management screens available.
- Club Admin: Bottom navigation replaced by side navigation rail (desktop) or hamburger menu (mobile) with full admin sections: Members, Contracts, Billing, Resources, Events, Communication, Settings.
- Higher admins: Same admin layout with additional sections: Organization hierarchy, Cross-org reports, Platform settings.
- Vendor Admin: Side navigation with platform-level sections: Customers, CRM Pipeline, Support Queue, System Health, Configuration. Cross-tenant context selector.
Role Switching
Users who hold multiple roles (e.g., a club admin who is also a member at another gym) can switch roles via a role selector in the app header. The role switch changes the navigation structure, visible screens, and active tenant context without requiring a re-login.
Role Management Features
Based on the admin user manual, club admins manage roles through the following workflow:
- User list -- View all users for the current organization with their assigned roles, status, and last activity.
- Create user -- Enter name, email, and select role. The system sends an invitation email with a registration link.
- Invitation flow -- Invited users register with their email, set a password, and are automatically assigned the pre-selected role within the inviting organization.
- Role assignment -- Admins can assign or revoke roles. A user can hold different roles in different organizations (e.g., admin at Club A, member at Club B).
- Permission audit -- Admins can view the effective permission set for any user, showing which permissions come from which role.
- Deactivation -- Deactivating a user preserves their data and history but prevents login and removes all active sessions.
Constraints
- A user can only assign roles at or below their own level (a club admin cannot create another club admin -- only a group admin or higher can).
- Role assignment is scoped to the organization: assigning "Club Admin" at Entity A does not grant any access to Entity B.
- System Admin role can only be assigned by another System Admin.
- Parent/Guardian linking requires consent from both parties (parent initiates, minor's admin approves or minor confirms via email if old enough).