Skip to content
ChannelWatch

DVR API Keys

This page covers credentials ChannelWatch uses to connect to Channels DVR servers. These are separate from the legacy shared X-API-Key that some upgraded ChannelWatch installations use for app access.

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

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.

Set a key during manual setup

Section titled “Set a key during manual setup”
  1. In the first-run wizard, choose the manual connection option.
  2. Enter the DVR name, host, and port.
  3. Enter the optional DVR API key in the manual form.
  4. Save the connection. Protected values go through the normal encrypted settings write path.
ChannelWatch Add DVR Manually form with sample Display Name, Host and Port, an empty optional API Key, Test Connection and a disabled Continue button
Add a DVR manuallyThe first-run manual connection form includes the optional Channels DVR API key. Captured from ChannelWatch v1.6.0 with safe demo data.View full-size screenshot

The v1.6.0 Settings > General DVR editor exposes names, hosts, and ports, but does not expose an API-key edit field. The Security tab reports encrypted storage; it is not a DVR-key editor.

Headless setup

Section titled “Headless setup”

The supported CHANNELS_DVR_SERVERS bootstrap value does not carry DVR API keys. Use the first-run manual form when the DVR needs a key. Directly placing plaintext credentials in settings.json bypasses the normal validation and encryption write path.

Key rotation

Section titled “Key rotation”

Rotating a DVR API key

Section titled “Rotating a DVR API key”

The v1.6.0 General editor does not provide a rotation control. Advanced operators can use the authenticated settings API to update the matching DVR entry’s api_key, preserving the rest of the settings document. The normal write path encrypts the replacement. See the settings API notes.

Take a private backup before changing credentials. Do not delete and re-add the DVR as a workaround: its identity is also used for history, routing, and session state. If you are not already using the settings API, ask for help through support rather than editing encrypted files by hand.

Rotating the credential-encryption key

Section titled “Rotating the credential-encryption key”

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

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

The command rotates /config/encryption.key and re-encrypts stored DVR api_key values and protected custom webhook URL/secret fields. Before replacing the files, it creates a private recovery snapshot under /config/backups/key-recovery/encryption-key-rotation-<timestamp>-<random-token>/ containing the pre-rotation settings.json, the previous encryption.key, and manifest.json. It does not create /config/encryption.key.bak.

Migration from v0.7

Section titled “Migration from v0.7”

Older releases stored DVR credentials in plaintext in settings.json. Current releases migrate protected credentials to encrypted form and manage /config/encryption.key for the running installation.

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

Section titled “Related pages”