Users & Roles

Meridian VMS uses a role-based access control (RBAC) system that controls which pages a user can view, which actions they can perform, and which locations they can access. Users authenticate with a username and password, and can be assigned multiple roles whose permissions are combined.

User management is at Settings > Access Control > Users, and role management is at Settings > Access Control > Roles.

User Accounts

Creating a User

1. Navigate to Settings > Users.
2. Click Add User.
3. Fill in the required fields:
   • Username — unique login identifier
   • Password — initial password for the account
4. Optionally fill in profile fields and assign roles.
5. Click Create User.

User Profile

Each user account has the following profile fields:

Field	Required	Description
username	Yes	Unique login name. Used for authentication.
password	Yes (on create)	Hashed and stored. Can be changed later; leave blank when editing to keep the current password.
email	No	Email address. Must be unique if provided.
first_name	No	First name, displayed in the user list and UI header.
last_name	No	Last name.
department	No	Organisational department, shown in the user list.
phone	No	Phone number for contact purposes.

Active/Disabled Toggle

Each user has an is_active flag:

• Active — the user can log in and access the system according to their role permissions.
• Disabled — the user cannot log in. Existing sessions will be invalidated shortly after the account is disabled.

Disabling vs deleting

Disable a user account instead of deleting it when you want to preserve the audit trail (alarm comments, assignment history) while preventing access. Disabled users appear greyed out in the user list.

Deleting a User

Deleting a user permanently removes the account and all associated role assignments. Alarm comments and assignments from the deleted user are preserved but the author reference is set to null.

Admin protection

The system requires at least one admin user. Deleting the last admin account is not permitted.

Authentication

Meridian VMS uses secure token-based authentication:

1. The user submits their username and password on the login screen.
2. On success, the server establishes an authenticated session.
3. Sessions are refreshed automatically by the web interface — no user action is required.
4. Sessions expire after a period of inactivity, redirecting the user to the login screen.

Admin seed

On first startup, the management server creates an initial admin user using the credentials configured during installation. This account has full admin privileges.

Roles

Roles define a set of permissions that can be assigned to users. The system ships with a built-in admin role, and administrators can create custom roles.

Creating a Role

1. Navigate to Settings > Roles.
2. Click Add Role.
3. Enter a role name and optional description.
4. Select the pages the role grants access to.
5. Select the actions the role permits.
6. Optionally restrict the role to specific locations.
7. Click Save.

Role Properties

Property	Description
name	Unique role name (e.g., “Operator”, “Site Manager”, “Viewer”)
description	Optional description of the role’s purpose
is_system	Whether this is a built-in system role (cannot be deleted)
pages	List of pages this role grants access to
actions	List of actions this role permits
locations	Optional list of location roots this role is scoped to

Page Permissions

Page permissions control which sections of the web interface a user can access:

Page	Description
dashboard	Main dashboard with statistics and overview
live	Live camera view with grid layout
playback	Recorded video playback with timeline
events	Detection event browser with thumbnails
detection	Real-time live object detection view
heatmap	Detection heatmap visualisation
settings	System administration and configuration
alarms	Alarm management dashboard

Settings page access

The settings page permission grants access to the full Settings area. There is no sub-page level permission within Settings — a user with the settings page permission can access all settings sections.

Action Permissions

Action permissions control specific operations a user can perform, independent of page access:

Action	Description
export_clips	Export video clips from playback
manage_alarms	Acknowledge, assign, and close alarms
edit_cameras	Add, edit, and delete cameras
manage_users	Add, edit, and delete user accounts
ptz_control	Control PTZ (pan-tilt-zoom) camera movements

Multi-Role Assignment

A user can be assigned multiple roles. When a user has multiple roles, their effective permissions are the union of all assigned roles:

• If Role A grants dashboard and live pages, and Role B grants playback and events pages, the user can access all four.
• If Role A permits export_clips and Role B permits manage_alarms, the user has both actions.
• Location restrictions are also unioned (see below).

Roles are assigned from the user edit form as checkboxes.

Location-Based Access Restriction

Roles can be scoped to specific locations in the hierarchy. When a role has location restrictions, users with that role can only see cameras, events, and data from those locations and their subtrees.

How Location Scoping Works

1. A role is created with one or more location roots (e.g., a region or a specific site).
2. When a user with that role makes an API request, the system expands each location root into its full subtree automatically.
3. The resulting set of location IDs is used to filter all camera queries.

Unrestricted Roles

A role with no location restrictions (empty locations list) grants access to cameras at all locations. This is useful for global administrators and operators who need to see the full deployment.

Combined Location Access

When a user has multiple roles with different location restrictions:

• If any of their roles is unrestricted, the user has access to all locations.
• Otherwise, the accessible locations are the union of all location subtrees from all roles.

Scenario

A user is assigned:

• Role “Gauteng Operator” scoped to the “Gauteng” region
• Role “Cape Town Viewer” scoped to the “Cape Town” city

The user can see all cameras in Gauteng (all cities, areas, and sites under it) plus all cameras in Cape Town (all areas and sites under it).

Where Location Filtering Applies

Location-based filtering is enforced on the following API endpoints:

Endpoint	Effect
GET /api/cameras	Only cameras at accessible locations are returned
GET /api/cameras/{id}	403 if camera is not at an accessible location
GET /api/cameras/{id}/live	403 if camera is not at an accessible location
GET /api/cameras/{id}/playback	403 if camera is not at an accessible location
GET /api/cameras/{id}/heatmap	403 if camera is not at an accessible location
GET /api/events	Only events from cameras at accessible locations

Admin vs Operator

The system has two conceptual user levels:

Admin : Users with is_admin = true bypass all permission checks. They have access to every page, every action, and every location. The admin flag is set on the initial seed user and can be granted to other users.

Non-Admin (Operator) : All other users. Their access is entirely determined by their assigned roles. A user with no roles has no access to any page or action.

Admin override

The is_admin flag is a hard override. Admin users do not need any role assignments — they automatically have full access. This is checked first in every permission resolver, and if true, all further permission logic is skipped.