Monitoring a Self-Hosted Hub

If your organisation runs its own BB Hub, you can watch it for brute-force sign-in attempts and other abuse with the monitoring tool you already use. This page shows you how to turn on Beyond Better's status endpoints and connect them to common monitors.

BB reports, your monitor alerts

Self-hosted hubs run on Linux, macOS, and Windows, behind anything from no proxy at all to a CDN. So BB doesn't send alerts itself. Instead, the hub's API serves read-only status endpoints over HTTP, and your monitor (Uptime Kuma, Nagios or Icinga, monit, Datadog, a Prometheus JSON exporter, a cron job, a Windows scheduled task) polls them and handles the alerting.

This page is for administrators of a self-hosted or Custom Hub. If you use the Cloud Hub, Beyond Better monitors it for you.

1. Enable the status endpoints

The status endpoints live under /api/v1/admin/status/ and need a bearer token. Add a monitoring token to the api section of the hub's global config.yaml, then restart the API:

api:
  # Read-only: accepted only for GET /api/v1/admin/status/*.
  # Give this one to monitoring tools.
  monitoringToken: <long random string>
  # Full admin access (also accepted on status endpoints).
  # Keep it out of monitoring tools.
  # adminToken: <long random string>

Generate a token with, for example, openssl rand -hex 32.

Use the monitoring token

The monitoring token can only read status. If a monitoring tool's configuration leaks, nobody gains admin access to your hub. Keep the admin token out of monitoring tools.

Response codes

  • 404: no token is configured, so the endpoints are switched off.
  • 401: the token is missing or wrong.

2. Check sign-in security

The auth-security endpoint reports brute-force and abuse indicators for sign-in and the other endpoints people can reach without signing in (sign-up, password reset, and so on).

curl -s -H "Authorization: Bearer $BB_MONITORING_TOKEN" \
  https://hub.example.com/api/v1/admin/status/auth-security

A typical response:

{
  "status": "warn",
  "reasons": ["warn: failed logins in the last 5 minutes (31, alert threshold 50)"],
  "generatedAt": "2026-10-27T07:12:00.000Z",
  "countingSince": "2026-10-27T01:03:11.000Z",
  "thresholds": { "loginFailures5m": 50, "rateLimited5m": 25, "emailsPerIp15m": 10 },
  "last5m": {
    "loginFailures": 31,
    "rateLimited": 4,
    "captchaChallenged": 2,
    "captchaInvalid": 0,
    "otherLoginErrors": 1
  },
  "last15m": { "...": "same fields" },
  "last60m": { "...": "same fields" },
  "topIps15m": [{ "ip": "203.0.113.7", "failures": 12, "distinctEmails": 1 }],
  "note": "Counts cover this API process only and reset when it restarts."
}

What the status means

The hub works out status for you, so your monitor only needs to check one field. It is ok, warn (at half a threshold), or alert (at or above a threshold). reasons explains which check tripped.

CheckWindowAlert at (default)Setting
Failed sign-ins (wrong credentials)5 min50alertLoginFailures
Requests refused for rate limiting (HTTP 429)5 min25alertRateLimited
Different emails one IP address failed to sign in as (credential stuffing)15 min10alertEmailsPerIp

To change a threshold, set it under api.auth.rateLimit:

api:
  auth:
    rateLimit:
      alertLoginFailures: 100
      alertRateLimited: 50
      alertEmailsPerIp: 10

Behind a reverse proxy? Per-IP figures need the real client IP, or every request appears to come from the proxy. Set api.clientIp.header to the header your edge proxy sets (for example CF-Connecting-IP or X-Real-IP), or api.clientIp.trustedProxyHops to the number of proxies that append to X-Forwarded-For. Only set these if every request passes through those proxies.

Counts are per API process. They reset when the API restarts (countingSince shows when counting began). If you run several API instances, poll each one.

Privacy: the response never includes email addresses. It does include client IP addresses, which is one reason the endpoint needs a token.

3. Status-code mode for simple monitors

Many monitors only look at the HTTP status code. Add ?fail=alert (or ?fail=warn) to the URL and the endpoint returns 503 when the status is at or above that level, and 200 otherwise. The JSON body is the same either way.

https://hub.example.com/api/v1/admin/status/auth-security?fail=alert

Examples

Replace hub.example.com with your hub's address and keep the token in an environment variable or your monitor's secret store.

Uptime Kuma (or any HTTP keyword monitor)

  • Monitor type: HTTP(s) - Keyword
  • URL: https://hub.example.com/api/v1/admin/status/auth-security
  • Header: Authorization: Bearer <token>
  • Keyword: "status":"ok"

Or use a plain HTTP monitor on the ?fail=alert URL.

Nagios or Icinga (check_http)

check_http -S -H hub.example.com \
  -u '/api/v1/admin/status/auth-security?fail=alert' \
  -k "Authorization: Bearer $BB_MONITORING_TOKEN" -e 200

cron and curl (Linux and macOS)

curl -sf exits with an error on a 503, so the mail command runs only when there's an alert:

curl -sf -H "Authorization: Bearer $BB_MONITORING_TOKEN" \
  'https://hub.example.com/api/v1/admin/status/auth-security?fail=alert' >/dev/null \
  || echo "BB auth security alert" | mail -s "BB alert" admin@example.com

Windows (PowerShell scheduled task)

This writes a warning to the Application event log whenever the status isn't ok:

$r = Invoke-RestMethod -Uri 'https://hub.example.com/api/v1/admin/status/auth-security' `
  -Headers @{ Authorization = "Bearer $env:BB_MONITORING_TOKEN" }
if ($r.status -ne 'ok') { Write-EventLog -LogName Application -Source 'BB' -EventId 1 `
  -EntryType Warning -Message ($r.reasons -join '; ') }

monit

A small check script calls the endpoint and exits with a different code for each result. It needs curl and jq, and reads the token from a file only root can read. Save it as /usr/local/bin/check-bb-auth-security.sh and make it executable:

#!/usr/bin/env bash
# Exit codes: 0 ok, 1 alert, 2 warn, 3 can't check
URL='https://hub.example.com/api/v1/admin/status/auth-security'
TOKEN=$(cat /etc/bb-monitoring-token 2>/dev/null)
[ -n "$TOKEN" ] || { echo "Monitoring token not found"; exit 3; }

body=$(curl -sf --max-time 10 -H "Authorization: Bearer $TOKEN" "$URL") \
  || { echo "Status endpoint unreachable or token rejected"; exit 3; }

status=$(echo "$body" | jq -r '.status')
reasons=$(echo "$body" | jq -r '.reasons // [] | join("; ")')

case "$status" in
  ok)    exit 0 ;;
  alert) echo "BB auth security ALERT: $reasons"; exit 1 ;;
  warn)  echo "BB auth security warning: $reasons"; exit 2 ;;
  *)     echo "Unexpected status: $status"; exit 3 ;;
esac

Then add a check program to your monit configuration. monit includes the script's output in the alert, so you see which check tripped:

check program bb-auth-security with path /usr/local/bin/check-bb-auth-security.sh
  every 2 cycles
  if status != 0 then alert

To treat each result differently (for example, page someone on an alert but only email on a warning), use separate if status = 1, if status = 2, and if status = 3 rules with their own actions.

Next Steps

Last updated: October 30, 2026