🔐 Access Protection

The CoolerControl Web UI uses a single admin user (CCAdmin) with password-based authentication. By default, the daemon binds to the local loopback interface and starts with a default password that must be changed on first use.

Changing the Password

Open the Access Protection menu from the UI and set a new password. The default password must be changed on first use and cannot be reused. Your current password is required to set a new one.

WARNING

All active sessions are invalidated when the password is changed. Any other connected UI clients will need to log in again.

Resetting the Password

To reset the password back to the default, run:

sudo coolercontrold --reset-password

Access Tokens

Access tokens provide stateless authentication for plugins, external services (e.g., cctv), and scripts that need to interact with the CoolerControl API. Tokens avoid exposing the admin password and can be scoped with an expiry date and a descriptive label so you know what each one is for.

Token Rights: Read-Only vs Write Access

Tokens can be created with either Write Access or Read-Only access:

Right	What it can do
Write Access	Full API access: read data and change settings, profiles, and controls
Read-Only	Read data only (sensors, status, device info). Cannot modify any settings

Use read-only tokens for monitoring integrations (dashboards, alerting, Prometheus scrapers) and write-access tokens only where configuration changes are needed (e.g., a home-automation flow that switches cooling Modes).

Creating a Token

1. Open the Access Protection menu from the UI.
2. Under Access Tokens, click Create Token.
3. Enter a label that identifies the token's purpose (e.g., cctv, monitoring).
4. Optionally set an expiry date to automatically invalidate the token after a given date.
5. Toggle Write Access on if the token needs to modify settings; leave it off for read-only access.
6. Click Create — the raw token is displayed once. Copy it immediately; it cannot be retrieved again.

Token format: cc_<uuid> (e.g., cc_550e8400e29b41d4a716446655440000)

Managing Tokens

The Access Tokens table shows all existing tokens with the following columns:

Column	Description
Label	The name you gave the token at creation
Access	Write or Read-Only — the rights granted to this token
Created	When the token was created
Expires	Expiry date, or Never if no expiry was set
Last Used	The last time the token was used to authenticate; Never used if it has not been used yet

Use the Delete button to revoke a token. Deletion takes effect immediately - any service using the token loses access at once.

Using Tokens for Authentication

Include the token in every API request using the Authorization: Bearer header:

curl -H "Authorization: Bearer cc_550e8400..." http://localhost:11987/status

Plugin Authentication

TIP

Never hardcode tokens in scripts. Load them from an environment variable, a secrets manager, or a configuration file with restricted permissions (chmod 600).

Best Practices

• One token per service — Create a separate token for each integration so you can revoke one without affecting others.
• Use read-only tokens by default — Grant write access only when the integration actually needs to change settings. Monitoring scripts, dashboards, and Prometheus scrapers only need read-only access.
• Use descriptive labels — Names like home-assistant, cctv-alerts, or monitoring-script make it easy to audit which tokens are active.
• Set expiry dates — For time-limited access (e.g., a contractor, a test environment), set an expiry so the token is automatically invalidated.
• Monitor Last Used — Tokens that have never been used or haven't been used recently may be candidates for deletion.
• Rotate periodically — Create a replacement token, update the service, then delete the old token.
• Revoke immediately if a token may have been compromised — deletion takes effect at once.

For full API reference and endpoint details, see the REST API documentation.

Securing Remote Access

DANGER

Do not expose the daemon on a network without additional protections.

If remote access is required:

1. Set a strong password using the Access Protection menu.
2. Use TLS encryption — enabled by default for non-localhost connections with a self-signed certificate. See SSL/TLS for custom certificate options.
3. Consider a reverse proxy for TLS termination with trusted certificates. See Reverse Proxy.
4. Use a secure tunnel (VPN, SSH port forwarding, Tailscale) for access over untrusted networks. See Remote Access.
5. Restrict network access with firewall rules or by binding to a specific interface. See TCP Port and Address.

See Also

• Security Overview - Full security model reference including session management, security headers, and CORS policy
• SSL/TLS - TLS configuration and certificates
• Remote Access - Secure remote access options