API Security & Authentication

How evcc authenticates HTTP requests and how endpoints are classified by sensitivity.

Threat Model

evcc is designed for use within a trusted home network. The auth layer protects credential management, configuration changes, and system operations (logs, backup/restore/reset, shutdown). Read-only state and basic charging controls are intentionally unauthenticated.

Auth Modes

Mode	Trigger	Behavior
`Enabled`	default	password required; JWT or API key accepted
`Disabled`	`--disable-auth` flag	all auth checks skipped
`Locked`	demo mode	mutating endpoints return 403; reads still work

Mode is fixed at startup. The frontend mirrors the mode so admin actions can be greyed out and a banner shown.

Endpoint Sensitivity Tiers

Three tiers, by what the caller has to prove:

Public. No auth. State, loadpoint controls, login. Anyone on the network can read and operate.

Secure. Requires a valid session: either the auth cookie (browser, JWT) or an API key in the Authorization: Bearer … header (automation). Used for configuration and system administration.

Critical. Secure plus an additional admin-password check inside the handler. Used for destructive or credential-scoped operations.

For some Critical endpoints (backup, restore, reset) the password check is skipped when the caller is authenticated via API key, so unattended automation doesn't need to embed the admin password. For credential-management endpoints (rotate API key, change admin password) the password check is strict: a leaked API key must not be able to rotate itself or change the admin password.

Disabling auth short-circuits all checks.

Sessions

Two transports, no overlap:

Browsers use a session cookie (JWT, 90-day TTL, issued on login).
Automation uses an API key in the Authorization: Bearer … header.

API keys are random alphanumeric strings prefixed evcc_. The prefix makes leaked keys recognizable to secret-scanning tools.

A single API key per installation; regenerating replaces the previous one. Plaintext is shown to the user once at generation time and cannot be retrieved afterwards.

Credential Storage

Admin password and API key are stored as bcrypt hashes. The JWT signing secret is a per-installation random value. Plaintext credentials are never persisted.

Removing the admin password (CLI recovery) also clears the JWT secret and the API key, which invalidates all outstanding sessions and any previously-issued API key. Regenerating the API key replaces the stored hash; the previous key stops working immediately.

API Key Lifecycle

Two operations:

Status. Whether a key is configured. Secure tier; never returns plaintext.
Regenerate. Critical tier, strict password check. Returns the new plaintext key exactly once.

There is no delete operation: regenerating and discarding the new key achieves the same effect (the previous key stops working immediately).

Endpoint Matrix

Endpoint category	Tier	Additional Requirements
State / read-only / basic charging control	Public
Set or update admin password	Public	admin password
Configuration	Secure
System: logs, cache, shutdown	Secure
API key status	Secure
System: backup / restore / reset	Critical	api key or admin password
API key regenerate	Critical	admin password

Public endpoints accept any caller. Secure endpoints require a valid session (cookie or API key). Critical endpoints require extra authentication in the form of an admin password (or, for some, an API key).

Frontend

Auth management lives under General Config → Security, which links to two sub-flows: change admin password, and manage the API key. The API key flow has a reveal view that shows the plaintext exactly once with a copy-to-clipboard link.

When auth is disabled, the security modals show a warning banner and disable all action buttons. This is UI-only; the backend still accepts the underlying calls so legitimate automation against a disabled-auth instance keeps working.

OpenAPI

The OpenAPI spec declares two security schemes (cookie and bearer); protected operations accept either.

4.8 KiB Raw Blame History