Skip to content
ChannelWatch

Users and Permissions

Secure login protects the dashboard and separates administrator, operator, and viewer permissions in v1.6.5. ChannelWatch calls this capability RBAC in configuration and API fields, but you can think of it as users and permissions. It creates a local administrator account, uses browser sessions, and applies role checks to protected routes. Fresh setup also offers trusted-network no-auth for isolated networks where every client is trusted.

ChannelWatch users and permissions settings showing user sign-in, encrypted per-DVR API keys, session availability, and feed token status
Secure login settingsUsers and permissions report the current sign-in mode, session support, API-key fallback state, and encrypted per-DVR key storage. Captured from ChannelWatch v1.6.0 with safe demo data.View full-size screenshot

Role model

Section titled “Role model”

The backend defines three roles:

Role Access boundary
Admin Full access to protected settings and administrative actions
Operator Operational changes allowed by routes that require operator or higher
Viewer Read access on routes that permit viewer sessions

Role enforcement is live in v1.6.5. General multi-user administration is not: the shipped UI and API do not provide supported actions to add users, change another user’s role, disable users, or delete users. The current UI creates the first administrator and lets a signed-in user change their own credentials.

First-run setup

Section titled “First-run setup”

On a fresh install:

  1. Choose Secure login.
  2. Enter the first administrator username and password.
  3. Continue to DVR setup.

The setup flow uses these auth endpoints:

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

Choosing secure login persists rbac mode and removes the shared API key. The resulting security mode is RBAC_ONLY.

ChannelWatch sign-in screen with username and password fields for a secure user session
Session loginUser sign-in protects the dashboard with an assigned account and password. Captured from ChannelWatch v1.6.0 with safe demo data.View full-size screenshot

Environment first-admin bootstrap

Section titled “Environment first-admin bootstrap”

CW_ADMIN_USER and CW_ADMIN_PASS can create the initial administrator only when no users exist:

environment:
  CW_ADMIN_USER: "admin"
  CW_ADMIN_PASS: "<strong-admin-password>"

These variables create an account but do not select the app’s authentication mode. Fresh interactive setup should still choose Secure login. The environment path is mainly useful when saved settings already enable RBAC and the user table is empty. Remove the variables after the first account is created. They do not reset an existing administrator.

Lockout recovery

Section titled “Lockout recovery”

Reset an existing administrator password with the shipped doctor command:

Terminal window
docker exec -it channelwatch channelwatch doctor reset-admin-password --username admin

The interactive command prompts for the new password without putting it in shell history. CW_ADMIN_USER and CW_ADMIN_PASS are not an existing-account recovery path because bootstrap runs only when the user table is empty.

Session security

Section titled “Session security”

Secure login uses a channelwatch_session cookie and requires an X-CSRF-Token header for mutating session-authenticated requests. The cookie is HttpOnly, uses SameSite=Strict, and expires after 86400 seconds. ChannelWatch adds Secure on HTTPS requests, including trusted reverse-proxy HTTPS when the direct proxy address is listed in CW_TRUSTED_PROXIES.

The current auth routes are:

POST /api/v1/auth/login
POST /api/v1/auth/logout
GET  /api/v1/auth/whoami
POST /api/v1/auth/change-credentials
GET  /api/v1/auth/setup-status
POST /api/v1/auth/setup

Legacy API-key fallback

Section titled “Legacy API-key fallback”

Upgraded installations can report RBAC_WITH_API_KEY_FALLBACK when secure sessions are active and a legacy shared API key still exists. That key has full access and bypasses role checks. RBAC_ONLY confirms that the bypass is gone.

ChannelWatch v1.6.5 does not ship service-account management or token creation for named users. Do not remove a legacy API-key path that an integration still requires until that integration has a tested session-auth alternative.

Section titled “Related pages”