API Keys

An API key is a long-lived credential tied to a specific user account. It lets scripts, home-automation systems, dashboards, and other integrations call the MZAP API without going through the interactive login flow.

Each user has at most one API key. The key inherits the user’s role and assignments — an Operator’s key can do exactly what that Operator can do in the UI, nothing more. Keys do not expire, but admins can regenerate (which invalidates the previous key) or delete the user (which revokes the key permanently).

Key format

API keys look like this:

mzap_f4e3a09b12c4d7e56890abcdef0123456789fedcba0987654321

The prefix mzap_ followed by 48 hex characters makes the key easy to detect in logs and easy to match with regular expressions. Keys are generated from 24 cryptographically random bytes.

Creating or rotating a key

1. Open the Users tab as an admin.
2. Find the user’s row.
3. Click Regenerate Key. The new key replaces any existing one and is copied to your clipboard automatically.

There is no “create once, hide forever” flow — the full key is visible on the Users tab to admins, so you can recover it if you lose the clipboard copy. If that is a concern for your deployment, regenerate the key after distributing it and treat the admin account as the keystore.

To revoke a key without creating a new one, regenerate it and don’t store the new value, or disable/delete the user account.

Using a key

Send the key on every request in one of these ways:

X-API-Key header (preferred)

GET /api/players HTTP/1.1
Host: localhost:5000
X-API-Key: mzap_f4e3a09b12c4d7e56890abcdef0123456789fedcba0987654321

curl -H "X-API-Key: mzap_..." http://localhost:5000/api/players

Authorization: Bearer

Session tokens and API keys are both accepted on the Authorization: Bearer header, so any client library that already speaks OAuth-style bearer auth works unchanged.

Authorization: Bearer mzap_f4e3a09b12c4d7e56890abcdef0123456789fedcba0987654321

?apiKey= query parameter

Useful when the client can’t set custom headers — for example, passing an SSE URL directly to EventSource in the browser, or embedding a stream URL in another tool.

http://localhost:5000/api/stream/events?apiKey=mzap_...

Prefer headers when possible. Query parameters show up in server logs and browser histories.

What a key can do

A key carries the same permissions as its user, evaluated at request time (not at key creation time). If you change the user’s role or assignments, the key’s effective permissions change with it.

Practical implications:

• Issuing an Operator key for a home-automation integration limits the blast radius if the key leaks — it can only touch the players and zones you assigned.
• Issuing a Viewer key for a status dashboard prevents the dashboard from ever changing audio, even if it’s compromised.
• Use the Admin role for keys only when you genuinely need full control (e.g. a provisioning script).

A disabled user’s key is rejected (401 Unauthorized). Re-enabling the user restores the key.

Example: controlling volume from a script

#!/usr/bin/env bash
BASE="http://localhost:5000"
KEY="mzap_..."

# List players visible to this key
curl -s -H "X-API-Key: $KEY" "$BASE/api/players" | jq '.[] | {id, name}'

# Set the volume of a specific player to 50%
curl -s -X PUT \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"volume": 0.5}' \
  "$BASE/api/players/<player-id>/volume"

Example: subscribing to events

const key = 'mzap_...';
const events = new EventSource(
  `http://localhost:5000/api/stream/events?apiKey=${encodeURIComponent(key)}`,
);

events.onmessage = (e) => {
  const evt = JSON.parse(e.data);
  console.log(evt.type, evt.payload);
};

The stream only emits events for players and zones in the key-holder’s assignment list.

Security notes

• Treat API keys like passwords. Store them in your secrets manager or environment variables, not in source control.
• MZAP does not currently rate-limit authentication attempts. If you expose the API on an untrusted network, put it behind a reverse proxy that enforces rate limits and TLS.
• There is no audit log for per-request key usage in the current version. Use request logging on your reverse proxy if you need one.