API Keys

ChannelWatch stores a separate API key for each Channels DVR server you add. The key field is masked in the web UI so the value isn’t visible after you save it. The encrypted value is stored in /config/settings.json inside the container.

Caution

ChannelWatch encrypts stored DVR api_key values before writing them back to /config/settings.json, but that protection is intentionally narrow. Other settings in the file are not automatically treated as encrypted secrets, so you should still protect the mounted config volume with appropriate filesystem permissions.

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

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. The key is re-encrypted for storage in /config/settings.json and masked in the UI immediately.

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 1-based index for each server:

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

Caution

Credentials in environment variables are visible to anyone who can run docker inspect on the container. For shared hosts, prefer the web UI or direct settings save path, which stores DVR API keys in encrypted form inside /config/settings.json.

Key rotation

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 value is overwritten immediately.

Rotating the encryption key used for stored DVR API keys

If you need to re-encrypt all stored DVR API keys with a new key file, use the shipped doctor command:

docker exec channelwatch channelwatch doctor rotate-encryption-key

The current implementation rotates /config/encryption.key, re-encrypts stored DVR api_key values with the new key, and keeps encryption.key.bak as a recovery copy when an older key existed. The CLI parser and tests in the app repo confirm this command is now a shipped path.

Note

This workflow covers the per-DVR API-key encryption scope documented on this page. It does not mean every secret or every field in settings.json is encrypted at rest.

Migration from v0.7

Older releases stored DVR credentials in plaintext in settings.json. In the current release family, stored DVR API keys can be migrated into encrypted form, with /config/encryption.key created or loaded as needed by the Fernet helper.

If you’re upgrading from a much older install, keep the backup set and the matching encryption key material together so restores remain usable.

Related pages

• Security Modes — how the API key interacts with security modes
• Optional RBAC — user roles and the admin bootstrap flow where enabled
• Backup and Restore — what the backup zip contains and how to restore