srcfl · frahlg · Sep 3, 2026 · Aug 29, 2026 · Sep 3, 2026 · Sep 3, 2026
diff --git a/docs/operations.md b/docs/operations.md
@@ -174,6 +174,44 @@ The FTW app and Home Assistant MQTT are unchanged.
 Recovery: `curl` to `127.0.0.1`, or set `api.lan_auth: false` in
 `config.yaml` and restart Core.
 
+### "remote access to protected API routes is disabled"
+
+The full message is `remote access to protected API routes is disabled;
+configure FTW_API_TOKEN or use a local address`. The dashboard still loads —
+the message appears when a protected request (saving settings, starting an
+update, a scan) is refused. It means the request failed the locality rules
+above, and "local" is judged on the request, not on which network the
+browser sits on:
+
+1. **The address in the browser's address bar** must be a private or
+   loopback IP, `localhost`, or a `.local`/`.localhost`/`.home.arpa` name.
+2. **The address the connection arrives from** must be loopback, private, or
+   link-local.
+
+Being on the same LAN as the box satisfies neither by itself. The common
+ways to trip the boundary from the couch next to the Pi:
+
+- **A plain hostname without a dot** — `http://myhost:8080`. Since v2.2.1
+  a no-dot name is deliberately not local (a DNS-rebinding guard), so an
+  address that worked before an update stops working. Use the `.local`
+  name or the IP instead.
+- **A router-issued name with a dot in it** — `pi.lan`, `ftw.fritz.box`,
+  `box.home`. Only the suffixes listed above count as local names.
+- **Tailscale** — both `100.x.y.z` addresses (CGNAT space) and `*.ts.net`
+  names count as remote.
+- **IPv6** — when the name resolves to a global IPv6 address, the browser
+  connects from a global address and fails the second rule, even with a
+  `.local` name in the address bar.
+- **A reverse proxy or Home Assistant ingress reached through a public
+  URL** — the request arrives carrying the public hostname.
+
+The reliable fix for a browser is to open the UI through the box's private
+IPv4 address, for example `http://192.168.1.123:8080`. Setting
+`FTW_API_TOKEN` does not change what the built-in UI sends — the token is
+only for API clients that attach the `Authorization: Bearer` header, as
+described above — and a `?token=...` query parameter in the URL does
+nothing.
+
 ## Logs and health
 
 ```bash

diff --git a/docs/setup-guide/de.md b/docs/setup-guide/de.md
@@ -145,4 +145,5 @@ Wenn diese Adresse nicht funktioniert — probiere die IP-Adresse, die du aufges
 - **Das Lämpchen leuchtet gar nicht** → prüfe, ob das Netzteil richtig eingesteckt ist.
 - **Keine IP-Adresse zu finden** → starte den Router neu, warte 5 Minuten, schau nochmal.
 - **SSH sagt "Connection refused"** → warte noch etwas. Der erste Start dauert.
+- **Die Seite lädt, aber beim Ändern von Einstellungen oder beim Update erscheint "remote access to protected API routes is disabled"** → FTW nimmt Änderungen nur von Adressen an, die es als lokal erkennt. Öffne die Oberfläche über die IP-Adresse des Pi, z. B. `http://192.168.1.123:8080`. Warum das passiert — auch zu Hause — steht in [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled) (auf Englisch).
 - **Das alles hilft nicht** → schau auf unserem Discord vorbei und frage freundlich nach Hilfe: **https://discord.gg/25xcBzQaux**
diff --git a/docs/setup-guide/en.md b/docs/setup-guide/en.md
@@ -145,4 +145,5 @@ If that address doesn't work — try the IP address you wrote down, e.g. `http:/
 - **The light isn't on at all** → check that the power adapter is plugged in.
 - **Can't find the IP address** → restart the router, wait 5 minutes, look again.
 - **SSH says "Connection refused"** → wait a little longer. The first boot takes time.
+- **The page opens, but changing settings or updating shows "remote access to protected API routes is disabled"** → FTW only accepts changes from addresses it recognizes as local. Open the UI through the Pi's IP address, e.g. `http://192.168.1.123:8080`. Why this happens — even at home — is explained in [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled).
 - **None of this helps** → drop by our Discord and kindly ask for help: **https://discord.gg/25xcBzQaux**
diff --git a/docs/setup-guide/es.md b/docs/setup-guide/es.md
@@ -145,4 +145,5 @@ Si esa dirección no funciona — prueba con la dirección IP que apuntaste, p.
 - **La luz no se enciende nada** → revisa que el adaptador de corriente esté bien conectado.
 - **No encuentras la dirección IP** → reinicia el router, espera 5 minutos, vuelve a mirar.
 - **SSH dice "Connection refused"** → espera un poco más. El primer arranque tarda.
+- **La página abre, pero al cambiar ajustes o actualizar aparece "remote access to protected API routes is disabled"** → FTW solo acepta cambios desde direcciones que reconoce como locales. Abre la interfaz con la dirección IP de la Pi, p. ej. `http://192.168.1.123:8080`. El porqué — incluso en casa — se explica en [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled) (en inglés).
 - **Nada de esto funciona** → pásate por nuestro Discord y pide ayuda amablemente: **https://discord.gg/25xcBzQaux**
diff --git a/docs/setup-guide/fr.md b/docs/setup-guide/fr.md
@@ -145,4 +145,5 @@ Si cette adresse ne fonctionne pas — essayez l'adresse IP que vous avez notée
 - **La lumière ne s'allume pas du tout** → vérifiez que l'adaptateur secteur est bien branché.
 - **Pas d'adresse IP trouvée** → redémarrez la box, attendez 5 minutes, regardez à nouveau.
 - **SSH dit "Connection refused"** → attendez encore un peu. Le premier démarrage prend du temps.
+- **La page s'ouvre, mais modifier un réglage ou lancer une mise à jour affiche "remote access to protected API routes is disabled"** → FTW n'accepte les modifications que depuis des adresses qu'il reconnaît comme locales. Ouvrez l'interface via l'adresse IP du Pi, p. ex. `http://192.168.1.123:8080`. Le pourquoi — même à la maison — est expliqué dans [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled) (en anglais).
 - **Rien de tout cela ne marche** → passez sur notre Discord et demandez gentiment de l'aide : **https://discord.gg/25xcBzQaux**
diff --git a/docs/setup-guide/sv.md b/docs/setup-guide/sv.md
@@ -145,4 +145,5 @@ Fungerar inte den adressen — prova IP-adressen du skrev ner, t.ex. `http://192
 - **Lampan lyser inte alls** → kolla att strömadaptern sitter i.
 - **Hittar ingen IP-adress** → starta om routern, vänta 5 minuter, titta igen.
 - **SSH säger "Connection refused"** → vänta lite till. Första uppstarten tar tid.
+- **Sidan öppnas, men vid ändringar eller uppdatering står det "remote access to protected API routes is disabled"** → FTW tar bara emot ändringar från adresser den ser som lokala. Öppna gränssnittet via Pi:ns IP-adress, t.ex. `http://192.168.1.123:8080`. Varför det händer — även hemma — förklaras i [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled) (på engelska).
 - **Det hjälper inte** → kika in på vår Discord och fråga snällt om hjälp: **https://discord.gg/25xcBzQaux**