Role & Permission Model

February 2026 · 18 min

The 14 Built-In Roles

Bio Ecko ships with 14 pre-defined roles. Each role determines which modules a user can access and what actions they can perform.

Important: Roles are assigned per user. A user can have exactly ONE role within an organization. If someone needs both doctor and admin privileges, they are assigned the admin role (which includes clinical access).

Permission Levels -- CRUD Matrix

Each role has a CRUD (Create, Read, Update, Delete) permission set for each module:

Example Permission Matrix (simplified):

FC Responsibility: During configuration, verify that the default permission matrix matches the hospital's requirements. Some hospitals want nurses to create appointments; others do not. Document deviations clearly.

Row Level Security (RLS) -- How Data Isolation Works

Row Level Security is enforced at the PostgreSQL database level. It ensures that even if the application has a bug, data cannot leak across organizations.

How It Works:

1. Every table has an organization_id column
2. When a user logs in, their organization_id is embedded in their JWT token
3. PostgreSQL RLS policies automatically filter every query: WHERE organization_id = current_user_org()
4. A user from Hospital A literally cannot see Hospital B's data -- the database blocks it before the application code even runs

RLS Layers:

FC Relevance: When setting up a multi-branch hospital chain, test RLS thoroughly. Log in as a user from Branch A and verify you cannot see Branch B patients. This is a NABH audit point.

Platform Admin vs Organization Admin

Bio Ecko has two distinct admin levels:

FC Docs Access: The FC Training and FC Scenarios documentation sections are restricted to platform admins only. Regular organization admins and staff cannot see them.

FC Configuration:

• During implementation, the FC typically has platform admin access for setup
• At go-live handover, platform admin access is revoked and the hospital's IT admin gets organization admin access
• Document who has platform admin access at all times (compliance requirement)

Multi-Branch Access Control

For hospital chains with multiple branches, access control becomes more nuanced:

Scenario 1: Branch-Isolated Staff A receptionist at the Delhi branch should only see Delhi patients and appointments.

• Configuration: profiles.branch_id = 'delhi-branch-id'
• RLS filters queries to only show records from that branch

Scenario 2: Cross-Branch Doctors A senior cardiologist may consult at both Delhi and Mumbai branches.

• Configuration: profiles.branches = ['delhi-id', 'mumbai-id'] (multi-branch assignment)
• The doctor sees patients from both branches and can toggle between them

Scenario 3: Chain-Level Management The CFO needs to see financial reports across all branches.

• Configuration: profiles.role = 'admin' with no branch restriction
• The admin sees consolidated data across all branches

FC Checklist for Multi-Branch Setup:

• Define branch hierarchy in organization settings
• Assign each user to their correct branch(es)
• Configure shared master data (formulary, test catalogue) at org level
• Configure branch-specific data (tariffs, bed master) at branch level
• Test cross-branch isolation with real test accounts

Role Assignment Best Practices

Common mistakes FCs make during user setup and how to avoid them:

Day-1 Checklist:

1. Create all user accounts with correct roles and branches
2. Set temporary passwords and mark "must change on first login"
3. Have each user log in and verify they see only their hub/modules
4. Test one user from each role to verify permission boundaries

VIP and Sensitive Record Access

Some hospitals require extra protection for certain patients (VIPs, celebrities, staff members receiving treatment, psychiatric patients):

Bio Ecko's Approach:

• A patient can be flagged as is_vip = true or sensitivity_level = 'restricted'
• When flagged, only the attending doctor and explicitly authorized users can view that patient's records
• Other users see the patient name redacted as ***RESTRICTED*** in lists
• Access attempts are logged in the audit trail

FC Configuration:

• Enable VIP flagging in Patient Registration settings
• Define who can flag/unflag a patient as VIP (typically admin + attending doctor only)
• Train registration and nursing staff on the VIP workflow
• During NABH audit prep, verify the VIP audit trail is complete

Emergency Break-Glass Access

In a medical emergency, a doctor may need to access a restricted patient's record (e.g., an unconscious VIP patient in the ED).

Break-Glass Protocol:

1. The doctor clicks "Emergency Access" on the restricted record
2. A reason is mandatory (free text + category: emergency, clinical need, etc.)
3. Access is granted immediately -- no approval wait
4. An alert is sent to the admin and the patient's attending doctor
5. The break-glass event is logged in the audit trail with full details
6. The admin reviews break-glass events weekly and follows up on any misuse

FC Configuration:

• Enable break-glass in Security Settings
• Configure alert recipients (admin, quality officer)
• Include break-glass review in the monthly quality audit checklist
• Train ED staff on when break-glass is appropriate vs when to call the attending doctor first

Notes

Related topics