Skip to main content
ALTCHA®

Listeners & reverse proxy

Sentinel can serve its API, the public widget endpoints, the admin UI, and Prometheus metrics on separate listeners. This page shows which paths to expose, how to put Sentinel behind a reverse proxy or CDN so that it sees the real client IP and host, and how to serve it over HTTPS.

Every key mentioned here is listed with its default in the Configuration reference. Listener changes take effect after a restart.

The four listeners

Only the main listener is on by default. Each listener has its own host, port, client IP settings, allowed_hosts, and tls. Nothing is inherited from [server] except the connection timeouts.

ListenerSectionDefault addressServes
Main API[server]0.0.0.0:3000, onEvery /v2 route, GET /, GET /.health, and the honeypot paths
Public widget API[server.public_api]0.0.0.0:3003, offGET/POST /v2/challenge, GET /v2/challenge/audio/…, POST /v2/verify, GET /v2/inspect, and GET /
Admin UI[server.admin_ui]127.0.0.1:3002, offThe admin web app, plus /v2 exactly as on the main listener
Prometheus[prometheus]127.0.0.1:3001, offMetrics at /metrics

The honeypot paths are a fixed list of paths that only scanners request, such as /.env, /.git/config, and /wp-login.php. A hit answers 404 and reports the client IP as a probe threat signal. If your proxy forwards every path to the main or public listener, the honeypot sees those scanners too.

Main API

[server] serves everything: the widget, the backend detection APIs, sign-in, and management. GET / answers {"ok":true} without touching storage, for load balancer probes and healthcheck. GET /.health reports the storage status and, by default, answers only clients on private networks; see Health endpoint.

Public widget API

[server.public_api] serves only what a browser needs, so you can publish it to the internet and keep the main listener on a private network. Every other /v2 path answers 404 NOT_FOUND, and GET /.health isn't served. GET /v2/inspect is served while [inspect] enabled is true (the default). Set verify_signature = true to also serve POST /v2/verify/signature here, for backends that can only reach the public address.

[server.public_api]
enabled  = true
base_url = "https://captcha.example.com"

When this listener is on, the admin UI builds the challenge URL that API keys → Copy challenge URL copies from its base_url and port, instead of the main listener's.

Admin UI

[server.admin_ui] serves the web app and the whole /v2 API on the same origin, because the app calls the API relative to its own URL. It binds to 127.0.0.1 by default, so you must set host = "0.0.0.0" to reach it from outside a container.

[server.admin_ui]
enabled     = true
host        = "0.0.0.0"
allowed_ips = ["192.0.2.0/24"]    # your office or VPN; others get 403
base_url    = "https://admin.sentinel.example.com"
  • allowed_ips restricts both the app's files and /v2 on this port. A client outside the list gets 403 with the plain-text body forbidden. The client IP is resolved with this listener's own trusted_proxies and client_ip_header, so behind a proxy, list the proxy there; otherwise every request appears to come from the proxy.
  • dir serves an app build from a directory instead of the copy embedded in the binary. The release image embeds the app, so leave it unset there.
  • api_reference (default true) offers the API reference page at #/api-reference. It's public (no sign-in) and renders GET /v2/openapi.json. Set it to false to hide it.
  • base_url is the app's public URL. It's also the OAuth redirect and passkey URL unless [auth] base_url is set; see Admin sign-in & SSO.
  • HTTPS. The session cookie is Secure, so outside localhost serve the app over HTTPS: set tls, or put a TLS proxy in front.

The app also works under a path prefix. Map https://example.com/admin/ to this listener's / (strip the prefix, and redirect /admin to /admin/), and include the prefix in base_url: "https://example.com/admin".

Prometheus

[prometheus] serves metrics on their own port. It has no trusted_proxies: allowed_ips checks the TCP peer, and allowed_hosts checks the Host header alone. Protect it with bearer_token or allowed_ips if you bind it beyond loopback. See Monitoring & metrics.

Choose what to expose

Publish only what each caller needs. A common layout is the public listener on the internet, the main listener on the private network your backends use, and the admin UI behind a VPN or an IP allowlist.

PathCalled byExpose
/v2/challenge, /v2/challenge/audio/…, /v2/verifyVisitors' browsers (the widget)Internet, preferably through [server.public_api]
/v2/inspectBrowsers or your backendInternet if the browser calls it, else private
/v2/classifier, /v2/verify/signature, and the other detection APIsYour backend, with a restricted or full keyPrivate network, or the internet over HTTPS if your backends are elsewhere
/v2/auth/…, management routes, the admin appAdminsAdmin UI listener only, behind a VPN or allowed_ips
GET /Load balancers, healthcheckLoad balancer only
GET /.healthUptime monitoringPrivate network (health_allowed_ips)
/metricsPrometheusPrivate network

Which credential each path accepts is listed in the credential matrix.

Behind a reverse proxy or CDN

A proxy changes three things Sentinel relies on: the client IP, the host the client addressed, and the public URL. Set the matching keys on every listener that sits behind the proxy.

Client IP

Sentinel uses the client IP for rate limits, penalties, threat lists, IP rules, request logs, and allowed_ips. On each listener it resolves the IP in this order:

  1. client_ip_header, if set and present with a single valid IP, for example CF-Connecting-IP, Fastly-Client-IP, or True-Client-IP from a CDN. When trusted_proxies is empty, it's accepted from any peer; otherwise only from those proxies.
  2. X-Forwarded-For, if the TCP peer is in trusted_proxies. Sentinel walks the list from the right and takes the first address that isn't a trusted proxy, so entries a client adds on the left are ignored. If every hop is trusted, it takes the leftmost.
  3. X-Real-IP, if the peer is trusted and X-Forwarded-For is absent.
  4. The TCP peer otherwise.

trusted_proxies takes IPs and CIDRs. The standard Forwarded header isn't read, so configure your proxy to send X-Forwarded-For.

Host and allowed hosts

allowed_hosts lists the hosts a listener answers for. A request addressed to any other host gets 421 Misdirected Request with the plain-text body misdirected request. This guards against DNS rebinding, where a page on an attacker's domain that resolves to Sentinel calls the API through a visitor's browser. Each listener has its own list; empty (the default) allows any host.

[server.public_api]
allowed_hosts = ["captcha.example.com"]
  • Entries are host names, IPs, or *.example.com, which matches subdomains of example.com but not example.com itself. Ports are ignored.
  • The host is the listener's forwarded_host_header when set and sent by a trusted peer (any peer while trusted_proxies is empty), else Host. Most proxies pass Host through unchanged, so you only need forwarded_host_header (for example X-Forwarded-Host) if your proxy rewrites Host. Web Bot Auth also verifies signatures against this host.
  • On the main and public listeners only /v2 (and the /v1 aliases) is checked. GET /, GET /.health, and the honeypot paths answer any host, so probes that address the IP keep working.

The full matching rules are in Allowed hosts.

Public URL

Set base_url to the public URL of each listener that answers the widget. Its path prefixes the URLs Sentinel hands to the widget: verifyUrl, the HIS url, and the code challenge audio. These URLs are root-relative, and the widget resolves them against the challenge URL. With base_url = "https://example.com/sentinel", verifyUrl is /sentinel/v2/verify; without a path, it's /v2/verify. See Serving Sentinel under a path or another domain.

[server] base_url is also the OAuth and passkey URL, unless [auth] base_url or an enabled [server.admin_ui] base_url is set. A base_url must be an http or https URL without query, fragment, or credentials.

Example configuration

This example publishes the widget at captcha.example.com and the admin UI at admin.sentinel.example.com through one proxy at 10.0.0.10. Sentinel runs at 10.0.0.20, and backends call the main listener on the private network.

[server]
host = "0.0.0.0"
port = 3000
allowed_hosts = ["sentinel.internal", "10.0.0.20"]   # names your backends use

[server.public_api]
enabled         = true
host            = "0.0.0.0"
port            = 3003
trusted_proxies = ["10.0.0.10"]
allowed_hosts   = ["captcha.example.com"]
base_url        = "https://captcha.example.com"

[server.admin_ui]
enabled         = true
host            = "0.0.0.0"
port            = 3002
trusted_proxies = ["10.0.0.10"]
allowed_ips     = ["192.0.2.0/24"]   # office or VPN egress, as forwarded by the proxy
allowed_hosts   = ["admin.sentinel.example.com"]
base_url        = "https://admin.sentinel.example.com"
upstream sentinel_widget {
    server 10.0.0.20:3003;
    keepalive 16;
}

upstream sentinel_admin {
    server 10.0.0.20:3002;
    keepalive 4;
}

server {
    listen 443 ssl;
    http2 on;
    server_name captcha.example.com;
    ssl_certificate     /etc/nginx/tls/captcha.example.com.pem;
    ssl_certificate_key /etc/nginx/tls/captcha.example.com.key;

    location / {
        proxy_pass http://sentinel_widget;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

server {
    listen 443 ssl;
    http2 on;
    server_name admin.sentinel.example.com;
    ssl_certificate     /etc/nginx/tls/admin.sentinel.example.com.pem;
    ssl_certificate_key /etc/nginx/tls/admin.sentinel.example.com.key;

    location / {
        proxy_pass http://sentinel_admin;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 100m;   # snapshot restores upload through the app
    }
}

proxy_set_header Host $host keeps the original host, so allowed_hosts works without forwarded_host_header. proxy_http_version 1.1 with an empty Connection header lets nginx reuse connections to Sentinel.

captcha.example.com {
	reverse_proxy 10.0.0.20:3003
}

admin.sentinel.example.com {
	reverse_proxy 10.0.0.20:3002
}

Caddy obtains the certificates, passes Host through unchanged, and sets X-Forwarded-For to the client IP, so the TOML above needs no other change.

If your proxy also forwards GET /.health to the main listener, list the proxy in [server] trusted_proxies. A request that carries X-Forwarded-For or X-Real-IP from a peer outside trusted_proxies gets 403 IP_NOT_ALLOWED there.

HTTPS

You can terminate TLS in Sentinel or at a proxy.

Built-in tlsTLS at a proxy or load balancer
Setuptls = { cert = "…", key = "…" } on each listener: a PEM chain (leaf first) and its keyCertificates live on the proxy; Sentinel listens on plain HTTP on a private network
ProtocolsTLS 1.2 and 1.3; HTTP/2 and HTTP/1.1 by ALPNWhatever the proxy offers
RenewalFiles are read at startup, so a renewed certificate needs a restartHandled by the proxy (for example Caddy or cert-manager) without touching Sentinel
Client certificatesNot supported (no mutual TLS)Depends on the proxy
Pick it whenSentinel is exposed directly, or you need encryption on the internal hop tooYou already run a proxy, need automatic renewal, or route several hosts through one address
[server.public_api]
enabled = true
tls     = { cert = "/etc/sentinel/tls/fullchain.pem", key = "/etc/sentinel/tls/privkey.pem" }

Paths are relative to the working directory, not to sentinel.toml. A missing file or a key that doesn't match stops startup; doctor --config-only reports it, for example:

FAIL  config.valid (server.admin_ui.tls)  server.admin_ui.tls.cert: reading missing.pem: I/O error: No such file or directory (os error 2).

Without tls, a listener serves HTTP/1.1, and HTTP/2 to clients that start with the HTTP/2 preface. See Listener TLS.

Connection timeouts

Four timeouts in [server] apply to every listener, including [server.public_api], [server.admin_ui], and [prometheus]:

[server]
idle_timeout        = "620s"   # close a connection with no request in flight (1s–24h)
header_read_timeout = "30s"    # wait for a complete request head (1s–10m)
body_read_timeout   = "30s"    # wait for the next part of a request body (1s–10m)
write_timeout       = "30s"    # wait on a client that isn't reading the response (1s–10m)

Keep idle_timeout above the keep-alive timeout of the proxy or load balancer in front of Sentinel: AWS ALB and nginx use 60s, Google Cloud load balancers 600s. If Sentinel closes an idle connection first, the proxy may send a request on it as it closes and return a 502 to the client. The default of 620s covers all three.

body_read_timeout and write_timeout count the wait between parts, so a slow but steady upload or download isn't cut off. A request whose body stalls gets 400 VALIDATION_ERROR. See Connection timeouts.

CORS

Sentinel sets CORS headers only where browsers on other origins need them:

  • Widget routes (/v2/challenge, /v2/challenge/audio/…, /v2/verify, /v2/inspect) allow any origin, with GET and POST and the Authorization and Content-Type headers, and cache preflights for 600 seconds. Cookies aren't allowed. Refusals such as rate limits and license errors carry the headers too. Restrict which sites may use a key with security-group origin rules; see CORS.
  • GET /v2/openapi.json allows any origin, for API viewers hosted elsewhere.
  • Everything else sends no CORS headers. Detection APIs are for servers, and the admin app calls /v2 on its own origin with a SameSite=Strict cookie.

Don't add CORS headers at the proxy; they would duplicate or widen Sentinel's.

Existing /v1 widget paths

[server] v1_compat = true serves /v1/challenge, /v1/challenge/audio/…, /v1/verify, and /v1/verify/signature as aliases of the /v2 routes, on the main, public, and admin listeners. It's for ALTCHA widget v3 or later whose challenge URL still points at /v1. No other /v1 path is served (POST /v1/classifier answers 404). Security-group rules and request logs see the /v2 path. See Existing /v1/challenge integrations.

Verify it works

Run these through your proxy once Sentinel is up.

  1. The listener answers. GET / answers on any host:

    curl https://captcha.example.com/
    {"ok":true}
  2. Wrong hosts are refused. Send a /v2 request with a host outside allowed_hosts:

    curl -i -H 'Host: wrong.example.org' http://10.0.0.20:3003/v2/challenge
    HTTP/1.1 421 Misdirected Request
    content-type: text/plain; charset=utf-8
    cache-control: no-store
    
    misdirected request
  3. The proxy is trusted. As root, run the doctor through the admin UI's public address and look at security.client_ip. It reports the TCP peer and whether it's in that listener's trusted_proxies:

    curl -s -X POST -H 'Authorization: Bearer <jwt>' \
      https://admin.sentinel.example.com/v2/doctor/_run \
      | jq '.data.checks[] | select(.id == "security.client_ip")'
    {
      "id": "security.client_ip",
      "category": "security",
      "status": "ok",
      "message": "Client IPs are derived as configured.",
      "details": { "forwarded": true, "peer": "10.0.0.10", "peerTrusted": true },
      …
    }

    If the proxy is missing from trusted_proxies, the check warns instead: This request came through a proxy at 10.0.0.10 that is not in trusted_proxies; every client appears as 10.0.0.10. Results are cached for 30 seconds, so wait before you run it again after a restart. See the API reference.

Before you go live, also check the listener items in the Production checklist.

Start typing to search...

↑ ↓ Navigate ↵ Select