Security Modes

ChannelWatch uses a security mode label to summarize how requests are authenticated. The values come from the backend security-status model, not from placeholder docs-only labels.

Caution

RBAC_WITH_API_KEY_FALLBACK and RBAC_ONLY are real source-backed states, but you should still read them carefully. They confirm that session auth and RBAC mode selection exist; they do not mean the shared API key has magically become low-privilege. In fallback mode, the API key still bypasses role checks.

The three modes

API_KEY_ONLY

The default mode, and still the simplest baseline. API requests are authenticated with a single shared X-API-Key. No per-user role separation is enforced.

• 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

This is the current transition mode for RBAC. The backend reports it when RBAC is enabled and a shared API key is still configured.

• Who it’s for: Multi-user deployments that want named-user sessions while keeping existing API-key automation working.
• Badge color: Yellow, to show that the API key still acts as a fallback.
• Tradeoff: The API key remains a full-access credential. Any script or integration that knows the key can bypass role checks.

Caution

RBAC_WITH_API_KEY_FALLBACK is best understood as a transitional hardening step. It gives you sessions and roles for browser users without forcing an immediate cutover for existing scripts.

RBAC_ONLY

This is the strict RBAC mode. The backend reports it when RBAC is enabled and no shared API key is present.

• Who it’s for: Shared home lab or multi-user deployments that need named accounts instead of one shared key.
• Badge color: Green.
• Tradeoff: You need at least one admin account before removing the shared API key, and any automation that depended on X-API-Key must move to the RBAC-compatible path you operate with.

The security mode badge

The badge is there to make the configured security posture visible at a glance. It shows the current mode name and a color indicator:

Badge	Meaning
Green RBAC_ONLY	Strict RBAC mode, no shared API key configured
Green API_KEY_ONLY	Single-key auth, public feeds disabled
Yellow RBAC_WITH_API_KEY_FALLBACK	RBAC is enabled, but the shared API key still exists as a bypass
Red API_KEY_ONLY	Single-key auth with public feeds enabled and unprotected

For current deployments, the most important practical signal is whether you are still in API_KEY_ONLY, whether public feeds are enabled, and whether fallback mode still leaves the shared key in place.

Checking the current mode via API

The security status endpoint returns the backend’s current status model:

GET /api/v1/security/status

Example response for the default shared-key setup:

{
  "security_mode": "API_KEY_ONLY",
  "auth_disabled": false,
  "rbac_enabled": false,
  "api_key_configured": true,
  "api_key_fallback_active": false,
  "session_auth_available": false,
  "session_setup_required": false,
  "encrypted_dvr_api_keys_at_rest": false,
  "encryption_key_path": "/config/encryption.key",
  "feeds": {
    "implemented": true,
    "ics_enabled": false,
    "rss_enabled": false,
    "atom_enabled": false
  }
}

Note

The field names above match the current backend response in source/ui/backend/main.py. encrypted_dvr_api_keys_at_rest is a boolean status field, not a Fernet metadata block, and it covers only stored per-DVR api_key values.

Choosing a mode

Scenario	Recommended mode
Solo home lab, only you access the dashboard	API_KEY_ONLY
You want named-user browser sessions but need existing scripts to keep working	RBAC_WITH_API_KEY_FALLBACK
You want strict named-user access with no shared-key bypass	RBAC_ONLY
Shared NAS or multi-user environment and you are not ready to manage users yet	API_KEY_ONLY, behind a trusted network boundary or reverse proxy

Switching modes

Mode-related settings live in Settings > Security. For the current release, the practical actions are:

• Keep or remove the shared API key, which determines whether RBAC stays in fallback mode or becomes RBAC_ONLY
• Turn public feeds on or off, and keep feed tokens enabled so calendar and activity URLs are not openly exposed
• Enable or disable RBAC depending on whether you want session auth and role-based browser access

Note

Encryption key rotation is not a Settings-page workflow. It is currently available through the doctor CLI and applies only to the per-DVR API-key encryption scope documented on the API-key page.

Note

SSO and OIDC are on the roadmap but are not part of v1.0. Today’s source-backed authentication surface is local auth: shared X-API-Key where configured, plus optional RBAC sessions and role checks.

Related pages

• API Keys (encrypted) — how per-DVR API keys are stored and rotated
• Optional RBAC — user roles, admin bootstrap, and the setup wizard
• CSP, CSRF, Cookies — web hardening defaults and the threat model