Optional RBAC

ChannelWatch v1.0 ships with a built-in role-based access control system. It’s disabled by default, so single-user home lab deployments work exactly as they did before with no extra configuration. When you do enable it, you get three distinct roles that let you share dashboard access without giving everyone full control.

Roles

Role	What they can do
Admin	Full access: manage DVR servers, change settings, manage users, rotate credentials, view all data
Operator	Can configure alerts and notification providers, view all dashboard data, but cannot manage users or rotate the encryption key
Viewer	Read-only access to the dashboard and activity history. Cannot change any settings

Note

RBAC is optional and off by default. If you never enable it, ChannelWatch behaves exactly as it did in v0.7: a single shared API key controls all access.

Enabling RBAC

RBAC is enabled in Settings > Security. Flip the Enable RBAC toggle. Before you do, make sure you have at least one admin user configured, or use the environment variable bootstrap described below.

When you enable RBAC, the security mode badge in the header changes to RBAC_WITH_API_KEY_FALLBACK (yellow). This means roles are active for browser sessions, but the existing API key still works as a bypass. To enforce roles strictly, disable the API key fallback in the same settings page.

Creating the first admin user

There are two ways to create the initial admin account.

Option 1: Environment variables (recommended for automation)

Set CW_ADMIN_USER and CW_ADMIN_PASS before the first startup with RBAC enabled:

environment:
  CW_ADMIN_USER: "admin"
  CW_ADMIN_PASS: "your-strong-password"

On startup, ChannelWatch checks whether any users exist. If none do, it creates an admin account using these credentials. The environment variables are not stored after the account is created — you can remove them from your compose file after the first run.

Caution

Choose a strong password. The admin account has full access to all settings, including credential rotation and user management. A weak password on a network-accessible service is a real risk.

Option 2: Setup wizard

If RBAC is enabled and no users exist, ChannelWatch blocks the UI with a setup wizard modal on first access. The wizard prompts you to create an admin username and password before you can proceed.

This path works well for interactive setups where you’re at the keyboard during first launch.

Managing users

Once you’re logged in as an admin, go to Settings > Users to:

• Add new users and assign roles
• Change a user’s role
• Reset a user’s password
• Disable or delete a user

There is no limit on the number of users.

Verifying the active mode

The security mode badge in the top-right corner of every page shows the current state. After enabling RBAC and disabling the API key fallback, the badge should show green RBAC_ONLY.

You can also check the current state via the API:

GET /api/v1/security/status

Look for "mode": "RBAC_ONLY" and "api_key_fallback_allowed": false to confirm strict enforcement is active.

Lockout recovery

If you lose access to all admin accounts, you can recover by setting CW_ADMIN_USER and CW_ADMIN_PASS environment variables and restarting the container. ChannelWatch will create a new admin account using those credentials if no users currently exist, or reset the named user’s password if the username matches an existing account.

environment:
  CW_ADMIN_USER: "admin"
  CW_ADMIN_PASS: "new-recovery-password"

After recovery, remove the environment variables and restart again to avoid leaving credentials in your compose file.

Session security

Browser sessions use secure, HTTP-only cookies with CSRF protection. Sessions expire after a configurable idle timeout (default: 24 hours). The session cookie is marked Secure when ChannelWatch detects it is running behind HTTPS.

Note

SSO and OIDC are on the roadmap but are not part of v1.0. User accounts are managed entirely within ChannelWatch’s own database.

RBAC and the API key

When RBAC is enabled, the relationship between the API key and roles depends on the active security mode:

• RBAC_WITH_API_KEY_FALLBACK: The API key bypasses all role checks. Any request with a valid API key has full admin-equivalent access.
• RBAC_ONLY: The API key is disabled. All requests must authenticate as a named user. Automation that previously used the API key must be updated to use a service account with an appropriate role.

See Security Modes for a full explanation of the three modes and when to use each.

Related pages

• Security Modes — the three modes and the security badge
• API Keys (encrypted) — how DVR credentials are stored
• CSP, CSRF, Cookies — web hardening defaults