Roles and Permissions

MZAP has three fixed roles. Every user has exactly one role. Permissions are enforced in two places: the web UI hides controls the user cannot use, and the API rejects requests with 401 Unauthorized or 403 Forbidden when the role is insufficient.

Admin

Admins have unrestricted access. They can:

• Create, edit, enable/disable, and delete users.
• Change any user's password and regenerate any user's API key.
• Enable or disable global authentication.
• Assign players and zones to Operators and Viewers.
• Lock the workspace, forcing all users to log in again.
• Create, delete, rename, and favourite players and zones; configure audio devices.
• Change application settings, AirPlay, stream failover, and auto-ducking.
• Create, edit, and delete jingles; manage EQ and compressor presets.
• Save, load, import, and export workspaces.

Admin always sees every player and zone. The assignment list is ignored for admin users.

Operator

Operators run day-to-day audio on their assigned players and zones. They can:

• Play, pause, stop, seek, skip, and jump to a track on assigned players.
• Adjust player and zone volume, mute, EQ, and compressor on assigned resources.
• Change an assigned player's playlist and playback mode, and load files into it.
• Change an assigned SoundMachine player's station, mix or schedule, and like or dislike its songs.
• Mark assigned players and zones as favorites, or remove them from favorites.
• Connect and disconnect their assigned players and zones in the routing matrix — see Routing.
• Play and stop jingles.
• Create and edit playlists.
• Create, edit, enable, disable, duplicate, delete, and manually run scheduler tasks.
• Browse the media library and internet radio catalog.
• Subscribe to real-time event and level streams (filtered to their assigned resources).

Operators cannot:

• Create, delete, or rename players and zones.
• Add, remove, or reconfigure audio devices.
• Create, edit, or delete jingles (they can play them).
• Import, export, duplicate, or delete playlists.
• Manage users or change global settings, AirPlay, failover, or auto-ducking.
• See or control players and zones that haven't been assigned to them.

Routing for operators

An Operator can route only between resources they own: the player and the zone must both be in their assignment list. A request that changes several zones at once is rejected as a whole if even one of those zones is not assigned — it is never partly applied.

Viewer

Viewers are read-only. They can:

• See the state of assigned players and zones (current track, position, state, volume).
• See the scheduler's task list, status, and execution log.
• Subscribe to event and level streams for their assigned resources.

Viewers cannot change anything — no transport, no volume, no jingles, and no manually running a scheduler task. Every write endpoint returns 403 Forbidden for viewer credentials. Use this role for dashboards, status displays, or kiosk screens that only need to observe.

Changed in 7.2.0.118 — check your Viewer accounts

Before 7.2.0.118 a Viewer could start, pause, stop, seek, and skip tracks on assigned players and could fire jingles, and an Operator could not route players to zones. Viewers are now strictly read-only and Operators gained routing.

If a Viewer account is used by someone who is expected to run playback, promote it to Operator. Otherwise their transport and jingle controls disappear and the API returns 403. Operator accounts need no change.

Permission matrix

Action	Admin	Operator	Viewer
Log in / log out	yes	yes	yes
View assigned players and zones	all	assigned	assigned
Play / pause / stop / seek / skip	yes	assigned	no
Adjust volume, mute, EQ, compressor	yes	assigned	no
Change a player's playlist or playback mode	yes	assigned	no
Change a SoundMachine player's source	yes	assigned	no
Mark players and zones as favorites	yes	assigned	no
Route players to zones	yes	assigned (both ends)	no
Play and stop jingles	yes	yes	no
Create, edit, delete jingles	yes	no	no
Create and edit playlists	yes	yes	no
Import, export, duplicate, delete playlists	yes	no	no
Manage and run scheduler tasks	yes	yes	no
View scheduler tasks and log	yes	yes	yes
Create, delete, rename players and zones	yes	no	no
Initialize or remove audio devices	yes	no	no
AirPlay, failover, auto-ducking settings	yes	no	no
Save, load, import, export workspaces	yes	no	no
Manage users and API keys	yes	no	no
Toggle global authentication	yes	no	no
Change application settings	yes	no	no
Lock the workspace	yes	no	no
Subscribe to event/level SSE streams	all events	filtered	filtered

"Assigned" means the operation is allowed only on resources in the user's assignment list (see Player and zone assignments).

UI behavior by role

The Users tab is only visible to admins. The Devices tab and the Settings save controls are also admin-only. Operators and Viewers see the tabs for day-to-day work — players, zones, playlists, jingles, library, radio, scheduler — and the desktop app shows only the controls their role can use:

• Viewers see no transport controls anywhere. Players cards, the player detail view, and the matrix batch bar hide play/pause/stop/next/previous; the seek bar shows position and duration but cannot be dragged; and double-clicking a queue track does nothing. The Players page shows a View only badge next to its title so the missing controls are explained.
• Operators can assign zones to their players and toggle routing in the matrix. Auto-ducking and AirPlay receiver settings stay admin-only.
• If the host ever refuses an action, a toast reads "You don't have permission to do that." instead of the action failing silently.
• Operators and Viewers start on the Players tab when they sign in, without the Welcome tab. Welcome is still available from Help → Welcome. Admins restore their saved layout as before, and only admins save the tab layout to the workspace — an Operator or Viewer rearranging tabs does not overwrite it.

Admins can also hide individual sidebar sections from a user — see Hiding sections from a user.

When a non-admin is logged in, the players and zones grids render only assigned resources. Assignment changes take effect on the next request; no reload is required.

API behavior by role

Every protected endpoint runs three checks in order:

1. Authenticated? No token (or an invalid one) returns 401 Unauthorized.
2. Role sufficient? A role below the endpoint's minimum returns 403 Forbidden.
3. Resource assigned? For endpoints that target a specific player or zone, the ID must be in the user's assignment list (admins bypass this check). Missing assignment returns 403 Forbidden.

Read-only listing endpoints return a filtered list for Operators and Viewers instead of 403. For example, GET /api/players returns every player for an admin but only assigned players for an operator.

Server-Sent Events from /api/stream/events and /api/stream/levels are filtered the same way: non-admins only receive events for resources assigned to them.

Fixed in 7.2.0.115

Permission rejections previously came back as 500 Internal Server Error rather than 403 Forbidden. This affected every permission check across the API — playback, zones, playlists, devices, scheduler, presets, users, and settings — so a Viewer or Operator attempting an admin-only action saw a generic server failure, and clients could not distinguish a permission problem from a genuine fault.

The same fault applied to license-gated endpoints, which are reachable even with authentication disabled: on a tier without a given feature, the endpoint returned 500 rather than 403.

Both now return 403 Forbidden as documented. No request that previously succeeded is affected, and no endpoint paths, request bodies, or response shapes changed.