diff --git a/README.md b/README.md
index ed88ebc..8b63d18 100644
--- a/README.md
+++ b/README.md
@@ -251,6 +251,13 @@ returned as JSON, with detail gated behind `DEBUG`.
   IP, inside 15 minutes answer `429` until 15 minutes have passed since the
   last failure. A successful login clears the username's failures; stale rows
   are purged as new ones are recorded.
+- **Behind Cloudflare** (or any proxy that hides the visitor), the IP the
+  throttle sees is the proxy's. Either restore real client IPs at the web
+  server (Apache `mod_remoteip` / Nginx `real_ip` with `CF-Connecting-IP` —
+  the better fix, it also corrects your logs), or set
+  `CLIENT_IP_HEADER` to `'CF-Connecting-IP'` in `config.php`. Only do either
+  if the origin is unreachable except through the proxy; otherwise the header
+  can be spoofed to dodge the per-IP limit.
 - The shipped `.htaccess` (Apache) denies direct access to `videos/`,
   `includes/`, `config.php` and `schema.sql` — without it, video URLs would
   bypass login entirely. Nginx setups need the equivalent `location` blocks,
diff --git a/api/auth.php b/api/auth.php
index 834a420..23038dc 100644
--- a/api/auth.php
+++ b/api/auth.php
@@ -27,7 +27,7 @@ verifyCsrfApi($data);
 $action   = $data['action'] ?? '';
 $username = trim($data['username'] ?? '');
 $password = $data['password'] ?? '';
-$ip       = $_SERVER['REMOTE_ADDR'] ?? '';
+$ip       = clientIp();
 
 switch ($action) {
     case 'login':
diff --git a/config.example.php b/config.example.php
index c43e991..98bc155 100644
--- a/config.example.php
+++ b/config.example.php
@@ -19,6 +19,14 @@ define('COMPLETE_THRESHOLD', 0.95);
 // Allow new users to self-register from the login page.
 define('ALLOW_REGISTRATION', true);
 
+// Only when the app sits behind a proxy that hides the visitor's address
+// (Cloudflare): the header carrying the real client IP, used by the login
+// brute-force throttle. Set this ONLY if the origin cannot be reached except
+// through that proxy — a directly reachable origin lets anyone spoof the
+// header and dodge the per-IP limit. Leave '' to use the connection address.
+//   define('CLIENT_IP_HEADER', 'CF-Connecting-IP');
+define('CLIENT_IP_HEADER', '');
+
 // Return the exception type, file:line and stack trace in API error responses.
 // Errors are written to the PHP error log either way — this only controls what
 // the browser is told, so leave it false on anything publicly reachable.
diff --git a/includes/auth.php b/includes/auth.php
index aeb0ddb..460ceb0 100644
--- a/includes/auth.php
+++ b/includes/auth.php
@@ -102,6 +102,25 @@ const LOGIN_FAIL_WINDOW   = 900;  // seconds
 const LOGIN_MAX_USER_FAILS = 5;
 const LOGIN_MAX_IP_FAILS   = 20;
 
+/**
+ * The client's IP for the throttle. Behind a proxy that hides the visitor
+ * (Cloudflare), REMOTE_ADDR is the proxy — set CLIENT_IP_HEADER in
+ * config.php to the header carrying the real address instead. Optional and
+ * off by default: installs whose config.php predates the setting keep using
+ * REMOTE_ADDR.
+ */
+function clientIp(): string
+{
+    if (defined('CLIENT_IP_HEADER') && CLIENT_IP_HEADER !== '') {
+        $key = 'HTTP_' . strtoupper(str_replace('-', '_', CLIENT_IP_HEADER));
+        $ip  = trim(explode(',', $_SERVER[$key] ?? '')[0]);
+        if ($ip !== '' && filter_var($ip, FILTER_VALIDATE_IP)) {
+            return $ip;
+        }
+    }
+    return $_SERVER['REMOTE_ADDR'] ?? '';
+}
+
 /** Seconds until this username/IP may try again — 0 means go ahead. */
 function loginRetryAfter(string $username, string $ip): int
 {