Overview

MZAP supports optional authentication with role-based access control. When enabled, users log in with a username and password, and their role determines what they can see and do. External systems can authenticate via API keys instead of interactive login.

When to enable authentication

By default, MZAP runs with authentication disabled — the UI loads without a login prompt and every request is treated as fully privileged. This is fine for a single-operator setup on a trusted machine.

Turn authentication on when:

• More than one person uses the same installation and you want an audit trail or per-user restrictions.
• Non-admin staff should control only specific players or zones (for example, a bartender who can adjust lounge volume but not the main hall).
• You expose the MZAP web UI or API on a network that isn’t fully trusted.
• You need to issue API keys for third-party integrations, scripts, or home-automation systems.

Enabling authentication

Authentication is toggled on the Users tab in MZAP. Before you can turn it on, at least one Admin user must exist — the UI blocks you from enabling auth without one so you can’t lock yourself out.

1. Open the Users tab.
2. Click Add User, fill in a username and password, and set the role to Admin.
3. Click Enable Authentication. Confirm the prompt.

From this point on, every browser session and API request must be authenticated. The next time you reload MZAP, a login dialog appears.

To turn it off again, click Disable Authentication on the Users tab. All existing sessions continue to work, and the login dialog stops appearing.

The three roles

MZAP ships with three fixed roles. See Roles and permissions for the full matrix.

• Admin — full access, including user management and settings.
• Operator — controls audio (play, pause, volume, routing) on the players and zones they are assigned to.
• Viewer — read-only; can watch state and levels but cannot change anything.

Admins always see every player and zone. Operators and Viewers see only the resources explicitly assigned to them — see Player and zone assignments.

Logging in

When authentication is enabled, the login dialog appears on startup and after the session is invalidated. Enter the username and password set by your administrator. MZAP validates the credentials, creates a session, and remembers you for subsequent requests.

Sessions are held in memory on the server. They stay valid until:

• You click Log out.
• The MZAP application restarts.
• An admin locks the workspace.
• An admin deletes your account or disables it.

There is no idle timeout or fixed expiry in the current version.

Authentication methods

The server accepts credentials in several forms. Most users never need to think about this — the web UI handles it automatically — but it matters when you build integrations.

Method	Where to put it	Used by
Session token	Authorization: Bearer <token>	Web UI after login
API key header	X-API-Key: <key>	Scripts, integrations
API key query	?apiKey=<key>	Server-Sent Events, media URLs
Session query	?token=<token>	Server-Sent Events from the UI

See API keys for how to generate and use keys.

Password policy

• Minimum length is 4 characters.
• Passwords are salted and hashed before being written to disk.
• The plain-text password is never stored or logged.
• There is no password-complexity enforcement or forced rotation — treat this as a local-venue tool, not a public-internet service.

Where user data lives

User accounts live on the MZAP host and follow the installation. Player and zone assignments live inside the active workspace file, so they travel with the workspace when you export or migrate a setup.

Because assignments are tied to usernames (not user IDs), you can move a workspace between installations as long as you recreate the same usernames on the target machine.