Skip to content
ChannelWatch

API Keys (encrypted)

ChannelWatch stores a separate API key for each Channels DVR server you add. These keys are encrypted before being written to disk, so a plaintext copy of your credentials never sits in settings.json.

How encryption works

Section titled “How encryption works”

When you save a DVR server with an API key, ChannelWatch encrypts the key using Fernet symmetric encryption before writing it to settings.json. The stored value looks like:

"api_key": "fernet:gAAAAABh..."

The encryption key itself lives at /config/encryption.key inside the container. ChannelWatch generates this file automatically on first startup using 32 bytes from the OS random source (os.urandom), then sets its permissions to 0600 (readable only by the process owner).

The encryption key file

Section titled “The encryption key file”
PropertyValue
Path/config/encryption.key (inside the container)
GeneratedAutomatically on first startup if the file does not exist
Permissions0600 (owner read/write only)
AlgorithmFernet (AES-128-CBC + HMAC-SHA256), 256-bit key material
Backup behaviorIncluded in the backup zip — treat the zip as a secret

Do not delete encryption.key. If the file is missing on a subsequent startup, ChannelWatch refuses to start with a clear error message rather than silently failing to decrypt stored credentials.

Per-DVR API keys

Section titled “Per-DVR API keys”

Each DVR server entry has its own API key field. This lets you use different credentials for each server without sharing a single key across your entire setup.

The API key is optional if your Channels DVR server does not require authentication. When left blank, ChannelWatch connects without a key.

Setting a key via the web UI

Section titled “Setting a key via the web UI”
  1. Go to Settings > DVR Servers.
  2. Select the server you want to update.
  3. Enter the API key in the API Key field.
  4. Click Save. ChannelWatch encrypts the key immediately before writing to disk.

Setting a key via environment variable

Section titled “Setting a key via environment variable”

For headless or automated deployments, you can supply per-DVR API keys through environment variables. The format uses a zero-based index for each server:

environment:
  CW_DVR_0_API_KEY: "your-dvr-api-key"
  CW_DVR_1_API_KEY: "second-dvr-api-key"

Environment variable values are encrypted and stored in settings.json on first write. Subsequent restarts read from the encrypted store, not the environment variable, unless the variable changes.

Key rotation

Section titled “Key rotation”

Rotating a DVR API key

Section titled “Rotating a DVR API key”

If you need to change the API key for a specific DVR server (for example, after rotating credentials on the Channels DVR side):

  1. Go to Settings > DVR Servers.
  2. Select the server.
  3. Enter the new API key.
  4. Click Save.

The old encrypted value is overwritten immediately.

Rotating the encryption key

Section titled “Rotating the encryption key”

If you need to rotate the /config/encryption.key itself (for example, after a suspected compromise of the config volume):

Terminal window
docker exec -it channelwatch channelwatch doctor rotate-encryption-key

This command:

  1. Generates a new 32-byte key from os.urandom.
  2. Re-encrypts all stored DVR API keys with the new key.
  3. Atomically replaces /config/encryption.key.

The rotation is transactional. If it fails partway through, the original key is preserved and an error is logged.

Migration from v0.7

Section titled “Migration from v0.7”

In v0.7, DVR credentials were stored in plaintext in settings.json. The v1.0 migration (schema v6 to v7) automatically encrypts any existing plaintext API keys in place during the first startup. A backup of your pre-migration settings.json is written to /config/backups/ before the migration runs.

You do not need to re-enter your credentials after upgrading.

Section titled “Related pages”