chmonitor — ClickHouse Monitoring Dashboard

Two-layer auth system for chmonitor — choose a browser auth provider and an optional API key layer for programmatic access.

chmonitor has two independent auth layers that work together on every /api/v1/* route. A request is allowed when either layer accepts it. The only fully public setup is CHM_AUTH_PROVIDER=none with no CHM_API_KEY_SECRET.

Auth provider — one of none, clerk, proxy, or trusted. Controls whether browser sessions are authenticated. Set the canonical CHM_AUTH_PROVIDER; the client VITE_AUTH_PROVIDER is derived from it at build time (you don't set it separately).
API key layer — always active when CHM_API_KEY_SECRET is set. Authenticates programmatic clients (MCP, scripts, CI) with signed chm_ Bearer tokens, independent of the provider.

Compare auth methods

Method	Who reads it	Browser / proxy auth	curl / MCP auth
Public (`none`)	—	open	none needed
API key	Provider-agnostic; active when `CHM_API_KEY_SECRET` set	—	`Authorization: Bearer chm_…`
Clerk	`clerk` provider	Clerk `__session` cookie	Clerk token or `chm_` key
Clerk OAuth (MCP only)	MCP server	—	OAuth bearer token
Proxy → Cloudflare Access	`proxy` provider	`Cf-Access-Jwt-Assertion` JWT	—
Proxy → trusted header (bare subject)	`proxy` provider	`X-Forwarded-User` + shared secret	shared secret header
Proxy → trusted headers (full profile)	`trusted` provider	forwarded headers (oauth2-proxy / Dex / Authelia)	shared secret header

Which one should I use?

Situation	Recommended setup
Local dev or internal network, no login needed	Public (`none`) — default
Hosted dashboard with user accounts and sign-in	Clerk
Behind Cloudflare Access	Proxy — `cloudflare-access`
Behind nginx/SSO with a bare identity header	Proxy — `trusted-header`
Behind oauth2-proxy / Dex / Authelia / Traefik ForwardAuth	Trusted (`trusted`)
MCP clients, scripts, CI pipelines	API key (`CHM_API_KEY_SECRET`) — add alongside any provider

How enforcement decides

Request evaluation order

For each /api/v1/* request, in order:

If CHM_AUTH_PROVIDER=none and CHM_API_KEY_SECRET is not set → allow (public).
The key-issuance route /api/v1/auth/api-key is exempt (it has its own auth).
A valid chm_ Bearer token → allow.
The active provider's check runs; if it authenticates → allow.
Otherwise → 401 { "error": "Authentication required" }.

All paths fail closed: a missing config or verification error resolves to "not authenticated".

Choose a provider

Public / no auth

Default open dashboard — any visitor can access all features. Best for local dev or trusted internal networks.

API keys

chm_ Bearer tokens for programmatic access — MCP clients, scripts, CI pipelines.

Clerk

Browser sign-in with Clerk sessions. Best for hosted dashboards with user accounts.

Cloudflare Access

proxy provider — Cloudflare Access JWT verification. Zero Trust, no shared secret needed.

Trusted header

proxy provider — bare identity subject via shared secret. Works with nginx or any reverse proxy.

Trusted proxy

trusted provider — full profile from forwarded headers. Works with oauth2-proxy, Dex, Authelia.

Environment variables — Authentication

Every CHM_* auth variable, its default, and where to set it.

Feature permissions

Gate individual features (agent, actions, tables) to authenticated users.

MCP server

Connect MCP clients with chm_ Bearer tokens or Clerk OAuth.

Authentication