Skip to content
ChannelWatch

Security Modes

ChannelWatch v1.0 introduces a security mode system that makes the current authentication posture visible at all times. The active mode is shown as a small badge in the top-right corner of every page in the web UI, so you always know exactly what level of protection is in effect.

The three modes

Section titled “The three modes”

API_KEY_ONLY

Section titled “API_KEY_ONLY”

The default mode. All requests to the web UI and API are authenticated with a single shared API key. RBAC is disabled.

  • Who it’s for: Single-user home lab deployments where only you access the dashboard.
  • Badge color: Green when public feeds are disabled; red when public feeds (ICS/RSS) are enabled without token protection.
  • Tradeoff: Simple to set up, but anyone with the API key has full access. There are no per-user roles.

RBAC_WITH_API_KEY_FALLBACK

Section titled “RBAC_WITH_API_KEY_FALLBACK”

RBAC is enabled, but the API key still works as a bypass for any request. This is a transitional mode.

  • Who it’s for: Deployments where you want to start using roles but still have automation or integrations that rely on the API key.
  • Badge color: Yellow, with a persistent notice: “API key still bypasses roles.”
  • Tradeoff: You get role-based access for browser sessions, but the API key remains a full-access credential. Any script or integration that knows the key can bypass role checks entirely.

RBAC_ONLY

Section titled “RBAC_ONLY”

RBAC is enabled and the API key bypass is disabled. Every request must authenticate as a named user with an assigned role.

  • Who it’s for: Multi-user households, shared home lab environments, or any deployment where you want to give some users read-only access.
  • Badge color: Green.
  • Tradeoff: Requires at least one admin user to be configured before you disable the API key. If you lock yourself out, you can recover by setting CW_ADMIN_USER and CW_ADMIN_PASS environment variables and restarting the container.

The security mode badge

Section titled “The security mode badge”

The badge appears in the top-right corner of the header on every page. It shows the current mode name and a color indicator:

BadgeMeaning
Green RBAC_ONLYStrict role enforcement, no API key bypass
Green API_KEY_ONLYSingle-key auth, public feeds disabled
Yellow RBAC_WITH_API_KEY_FALLBACKRoles active but API key still bypasses
Red API_KEY_ONLYSingle-key auth with public feeds enabled and unprotected

The badge is not decorative. It reflects the live computed state from Settings > Security and updates immediately when you change settings.

Checking the current mode via API

Section titled “Checking the current mode via API”

The security status endpoint returns the full computed state:

GET /api/v1/security/status

Example response:

{
  "mode": "RBAC_WITH_API_KEY_FALLBACK",
  "rbac_enabled": true,
  "api_key_enabled": true,
  "api_key_fallback_allowed": true,
  "user_count": 2,
  "encryption_at_rest": {
    "scheme": "fernet",
    "key_source": "/config/encryption.key",
    "strength": "256-bit symmetric"
  },
  "public_feeds": {
    "ics_enabled": false,
    "rss_enabled": false,
    "requires_token": true
  }
}

Choosing a mode

Section titled “Choosing a mode”
ScenarioRecommended mode
Solo home lab, only you access the dashboardAPI_KEY_ONLY
You want to give a family member read-only accessRBAC_ONLY
Migrating from API key to RBAC graduallyRBAC_WITH_API_KEY_FALLBACK (temporary)
Shared NAS or multi-user environmentRBAC_ONLY

Switching modes

Section titled “Switching modes”

All mode changes happen in Settings > Security. The page shows your current mode, explains what each change means, and offers one-click actions:

  • Disable API key fallback — moves from RBAC_WITH_API_KEY_FALLBACK to RBAC_ONLY
  • Require tokens on feeds — removes the red badge when public feeds are enabled
  • Rotate encryption key — generates a new /config/encryption.key and re-encrypts all stored credentials
Section titled “Related pages”