# Listeners & reverse proxy

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](/docs/sentinel/v2/reference/configuration/#server). 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](#connection-timeouts).

| Listener | Section | Default address | Serves |
| --- | --- | --- | --- |
| Main API | [`[server]`](/docs/sentinel/v2/reference/configuration/#server) | `0.0.0.0:3000`, on | Every `/v2` route, `GET /`, `GET /.health`, and the honeypot paths |
| Public widget API | [`[server.public_api]`](/docs/sentinel/v2/reference/configuration/#serverpublic_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]`](/docs/sentinel/v2/reference/configuration/#serveradmin_ui) | `127.0.0.1:3002`, off | The admin web app, plus `/v2` exactly as on the main listener |
| Prometheus | [`[prometheus]`](/docs/sentinel/v2/reference/configuration/#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`](/docs/sentinel/v2/reference/cli/#healthcheck). `GET /.health` reports the storage status and, by default, answers only clients on private networks; see [Health endpoint](/docs/sentinel/v2/reference/configuration/#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.

```toml
[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.

```toml
[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](/docs/sentinel/v2/security/sign-in/).
- **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](/docs/sentinel/v2/operations/monitoring/).

## 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](/docs/sentinel/v2/concepts/api-keys/#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`.

> **Warning:**
>
> With `trusted_proxies` empty, Sentinel accepts `client_ip_header` and `forwarded_host_header` from any peer, so any client that reaches the listener directly can choose its own IP and host. Either allow traffic only from the CDN or proxy, or list its addresses in `trusted_proxies`. `doctor` warns about an untrusted `client_ip_header` as `security.client_ip`.

### 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.

```toml
[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](/docs/sentinel/v2/reference/configuration/#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](/docs/sentinel/v2/integrate/widget/#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.

```toml
[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"
```

### nginx

```nginx
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.

### Caddy

```text
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 |

```toml
[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:

```text
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](/docs/sentinel/v2/reference/configuration/#listener-tls).

## Connection timeouts

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

```toml
[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](/docs/sentinel/v2/reference/configuration/#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](/docs/sentinel/v2/integrate/widget/#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](/docs/sentinel/v2/integrate/widget/#existing-v1challenge-integrations).

## Verify it works

Run these through your proxy once Sentinel is up.

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

```bash
curl https://captcha.example.com/
```

```json
{"ok":true}
```

2. **Wrong hosts are refused.** Send a `/v2` request with a host outside `allowed_hosts`:

```bash
curl -i -H 'Host: wrong.example.org' http://10.0.0.20:3003/v2/challenge
```

```http
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`:

```bash
curl -s -X POST -H 'Authorization: Bearer <jwt>' \
 https://admin.sentinel.example.com/v2/doctor/_run \
 | jq '.data.checks[] | select(.id == "security.client_ip")'
```

```json
{
 "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](/sentinel-api-docs-v2.html#tag/doctor/POST/v2/doctor/_run).

Before you go live, also check the listener items in the [Production checklist](/docs/sentinel/v2/security/production-checklist/).

## Related

- [How Sentinel works](/docs/sentinel/v2/concepts/)
- [Configuration reference: `[server]`](/docs/sentinel/v2/reference/configuration/#server)
- [Allowed hosts](/docs/sentinel/v2/reference/configuration/#allowed-hosts)
- [Listener TLS](/docs/sentinel/v2/reference/configuration/#listener-tls)
- [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/)
- [Widget integration](/docs/sentinel/v2/integrate/widget/)
- [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/)
- [Monitoring & metrics](/docs/sentinel/v2/operations/monitoring/)
- [Install Sentinel](/docs/sentinel/v2/install/)
