Optional RBAC

Caution

RBAC is no longer just a placeholder surface. The current backend ships login/logout/whoami/session endpoints, role checks on protected routes, and CSRF protection for session-backed writes. The important caveat is scope: if a shared API key is still configured, that key remains a full-access fallback and can bypass role checks.

ChannelWatch supports optional role-based access control. It stays disabled by default so single-user home lab deployments can keep using the shared API key with no extra setup. When enabled, it adds named users, browser sessions, and three distinct roles so you can share dashboard access without giving everyone full control.

Roles

Role	What they’ll be able to do
Admin	Full access: manage DVR servers, change settings, manage users, rotate credentials, view all data
Operator	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

If you never enable RBAC, ChannelWatch continues to behave like a single-key deployment. If you do enable RBAC but leave the shared API key configured, the key still acts as a full-access fallback.

Enabling RBAC

The current backend computes and reports three security modes from actual settings state:

1. Make sure you have at least one admin user configured before enabling RBAC, or use the environment variable bootstrap described below.
2. Flip the Enable RBAC toggle in Settings > Security.
3. If a shared API key is still configured, the security mode becomes RBAC_WITH_API_KEY_FALLBACK, meaning browser sessions and role checks are active but the API key still works as a bypass.
4. If you remove the shared API key after creating an admin account, the mode becomes RBAC_ONLY.

Creating the first admin user

The current source supports two bootstrap paths for 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, so you can remove them from your compose file after the first run.

Caution

Choose a strong password. The admin account will have 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 flow

If RBAC is enabled and no users exist, the auth API exposes setup status and first-user creation endpoints:

GET  /api/v1/auth/setup-status
POST /api/v1/auth/setup

That setup flow is what lets the UI prompt for the first admin username and password before regular session login can take over.

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

Managing users

Once logged in as an admin, ChannelWatch’s shipped RBAC model is designed around these role boundaries:

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

There will be 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, it reflects whether the shared API key is still present.

You can also check the current state via the API:

GET /api/v1/security/status

Look for "security_mode": "RBAC_ONLY" and "api_key_fallback_active": false to confirm the shared-key bypass is no longer active.

Note

The current backend and tests confirm that /api/v1/security/status really does report RBAC_WITH_API_KEY_FALLBACK and RBAC_ONLY when the corresponding settings state exists. Treat those values as source-backed status, not as future placeholders.

Lockout recovery

If you lose access before any user exists, you can recover by setting CW_ADMIN_USER and CW_ADMIN_PASS environment variables and restarting the container. ChannelWatch creates the bootstrap admin only when the user table is empty.

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 in the current RBAC flow use a channelwatch_session cookie plus an X-CSRF-Token header for mutating requests. In source, the session cookie is set with HttpOnly, Secure, SameSite=Strict, and a max_age of 86400 seconds.

Note

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

RBAC and the API key

When RBAC is active, the relationship between the API key and roles will depend on the 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.

Multi-user deployments

The intended workflow for a shared deployment:

1. Create the first admin account using env vars or the setup wizard.
2. Enable RBAC in Settings > Security.
3. Create Viewer or Operator accounts for other household members or team members.
4. Optionally disable the API key fallback to enforce strict role separation.
5. Update any automation scripts to use a service account with an appropriate role instead of the shared API key.

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