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.
| Listener | Section | Default address | Serves |
|---|---|---|---|
| Main API | [server] | 0.0.0.0:3000, on | Every /v2 route, GET /, GET /.health, and the honeypot paths |
| Public widget API | [server.public_api] | 0.0.0.0:3003, off | GET/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, off | The admin web app, plus /v2 exactly as on the main listener |
| Prometheus | [prometheus] | 127.0.0.1:3001, off | Metrics 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_ipsrestricts both the app's files and/v2on this port. A client outside the list gets403with the plain-text bodyforbidden. The client IP is resolved with this listener's owntrusted_proxiesandclient_ip_header, so behind a proxy, list the proxy there; otherwise every request appears to come from the proxy.dirserves 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(defaulttrue) offers the API reference page at#/api-reference. It's public (no sign-in) and rendersGET /v2/openapi.json. Set it tofalseto hide it.base_urlis the app's public URL. It's also the OAuth redirect and passkey URL unless[auth] base_urlis set; see Admin sign-in & SSO.- HTTPS. The session cookie is
Secure, so outsidelocalhostserve the app over HTTPS: settls, 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.
| Path | Called by | Expose |
|---|---|---|
/v2/challenge, /v2/challenge/audio/…, /v2/verify | Visitors' browsers (the widget) | Internet, preferably through [server.public_api] |
/v2/inspect | Browsers or your backend | Internet if the browser calls it, else private |
/v2/classifier, /v2/verify/signature, and the other detection APIs | Your backend, with a restricted or full key | Private network, or the internet over HTTPS if your backends are elsewhere |
/v2/auth/…, management routes, the admin app | Admins | Admin UI listener only, behind a VPN or allowed_ips |
GET / | Load balancers, healthcheck | Load balancer only |
GET /.health | Uptime monitoring | Private network (health_allowed_ips) |
/metrics | Prometheus | Private 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:
client_ip_header, if set and present with a single valid IP, for exampleCF-Connecting-IP,Fastly-Client-IP, orTrue-Client-IPfrom a CDN. Whentrusted_proxiesis empty, it's accepted from any peer; otherwise only from those proxies.X-Forwarded-For, if the TCP peer is intrusted_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.X-Real-IP, if the peer is trusted andX-Forwarded-Foris absent.- 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 ofexample.combut notexample.comitself. Ports are ignored. - The host is the listener's
forwarded_host_headerwhen set and sent by a trusted peer (any peer whiletrusted_proxiesis empty), elseHost. Most proxies passHostthrough unchanged, so you only needforwarded_host_header(for exampleX-Forwarded-Host) if your proxy rewritesHost. Web Bot Auth also verifies signatures against this host. - On the main and public listeners only
/v2(and the/v1aliases) 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 tls | TLS at a proxy or load balancer | |
|---|---|---|
| Setup | tls = { cert = "…", key = "…" } on each listener: a PEM chain (leaf first) and its key | Certificates live on the proxy; Sentinel listens on plain HTTP on a private network |
| Protocols | TLS 1.2 and 1.3; HTTP/2 and HTTP/1.1 by ALPN | Whatever the proxy offers |
| Renewal | Files are read at startup, so a renewed certificate needs a restart | Handled by the proxy (for example Caddy or cert-manager) without touching Sentinel |
| Client certificates | Not supported (no mutual TLS) | Depends on the proxy |
| Pick it when | Sentinel is exposed directly, or you need encryption on the internal hop too | You 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, withGETandPOSTand theAuthorizationandContent-Typeheaders, 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-grouporiginrules; see CORS. GET /v2/openapi.jsonallows any origin, for API viewers hosted elsewhere.- Everything else sends no CORS headers. Detection APIs are for servers, and the admin app calls
/v2on its own origin with aSameSite=Strictcookie.
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.
The listener answers.
GET /answers on any host:curl https://captcha.example.com/{"ok":true}Wrong hosts are refused. Send a
/v2request with a host outsideallowed_hosts:curl -i -H 'Host: wrong.example.org' http://10.0.0.20:3003/v2/challengeHTTP/1.1 421 Misdirected Request content-type: text/plain; charset=utf-8 cache-control: no-store misdirected requestThe 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'strusted_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.