Integrations
Use read-only API tokens for authenticated integrations.
Authentication notifications
Enable Authentication notifications on the Notifications page to send account access events through the existing configured provider. Both this trigger and the main notification switch must be enabled. The trigger defaults to off, including for existing installations. There are no separate destinations or event switches.
| Event | Application log level | Notification priority |
|---|---|---|
| Successful password sign-in | info | Normal |
| Successful password sign-in while passkeys are registered | warn | High |
| Successful passkey sign-in | info | Normal |
| Rejected password or passkey sign-in | warn | Normal |
| Successful account recovery | warn | High |
| Rejected recovery key | warn | High |
The first failed credential check is notified immediately. Additional failures are counted separately for password, passkey and recovery attempts, across all source IPs. At the end of the configured cooldown, one summary per method reports the additional count and the latest attempt’s timestamp and source IP. Successful events are sent individually. Changing notification settings discards pending summaries. Failure windows are held in memory and restart with the backend.
Events contain the timestamp, method, outcome and source IP resolved by Express’s configured proxy trust. They omit submitted usernames, passwords, recovery keys, passkey assertions, tokens and session identifiers. Browser cancellation before submitting a passkey assertion is not a backend credential check. Setup, legacy enrollment, API-token requests and password confirmation inside an existing session are not recorded as successful sign-ins. Requests rejected before credential verification, such as CSRF or rate-limit failures, keep their existing request diagnostics rather than generating authentication notifications.
Authentication event logging does not depend on notification switches, but still
respects LOG_LEVEL. For example, LOG_LEVEL=error filters out these events.
The UI’s recent application-log buffer is bounded and is not a persistent audit
archive; configure Docker or host log retention if needed.
Notification delivery is best effort and never waits inside authentication or recovery. At most eight authentication sends run concurrently; excess sends are skipped with an application warning. Failed delivery is logged without including provider response contents and is not automatically retried. Changing settings does not recall a send already in progress.
External Caddyfile change detection is a separate follow-up.
Prometheus Metrics
Enable Caddy metrics in the Metrics tab or Caddyfile. Use a metrics:read token for selected instances. CADDY_UI_PUBLIC_METRICS=true instead exposes metrics without authentication.
scrape_configs:
- job_name: caddy
static_configs:
- targets: ['caddy-ui-backend:3001']
metrics_path: /api/metrics/raw
authorization:
type: Bearer
credentials_file: /run/secrets/caddy_ui_metrics_token
http_headers:
X-Instance-Id:
values: ['default']
The endpoint includes upstream uptime history (instance_id, instance_name, upstream labels) and enabled route history (instance_id, instance_name, route), even with Caddy metrics disabled. Tokens include only permitted instances; administrator sessions and public scrapes include all:
| Metric | Description |
|---|---|
caddy_ui_upstream_up | Result of the most recent check (1 = online, 0 = offline) |
caddy_ui_upstream_uptime_ratio | Fraction of retained checks that were online (see UPTIME_HISTORY_RETENTION_DAYS) |
caddy_ui_upstream_state_duration_seconds | Time the upstream has been in its current state |
caddy_ui_route_up | Result of the most recent route check (1 = online, 0 = offline) |
caddy_ui_route_uptime_ratio | Fraction of retained route checks that were online |
caddy_ui_route_state_duration_seconds | Time the route has been in its current state |
caddy_ui_caddy_metrics_up | Whether Caddy’s /metrics could be scraped for the requested instance |
Upstreams that haven’t been checked in 5 minutes, and routes that haven’t been checked in 12.5 minutes (2.5 route check intervals), are omitted: they’ve been removed from the config, skipped, or their instance is unreachable.
Homepage Widget
The status endpoint returns enriched data for Homepage. Create a status:read token and supply it through Homepage’s environment substitution:
- Caddy:
href: https://caddy.home
icon: caddy.png
widget:
type: customapi
url: http://caddy-ui-backend:3001/api/status
headers:
Authorization: Bearer {{HOMEPAGE_VAR_CADDY_UI_TOKEN}}
X-Instance-Id: default
mappings:
- field: online
label: Status
format: text
remap:
- value: true
to: Online
- value: false
to: Offline
- field: routeCount
label: Routes
format: number
- field: upstreamsOnline
label: Upstreams
format: number
- field: uptime
label: Uptime
format: text