From 17241d67ab64c83e757bb0e9ae6f2d87f254563b Mon Sep 17 00:00:00 2001
From: CodeShell <122738806+CodeShellDev@users.noreply.github.com>
Date: Sat, 3 Jan 2026 20:11:22 +0100
Subject: [PATCH 1/2] add ratelimiting section

---
 docs/about.md                      | 19 ++++++++++---------
 docs/configuration/ratelimiting.md | 23 +++++++++++++++++++++++
 docs/features/features.md          |  5 +++++
 3 files changed, 38 insertions(+), 9 deletions(-)
 create mode 100644 docs/configuration/ratelimiting.md

diff --git a/docs/about.md b/docs/about.md
index 15c59a2c..ec8395a5 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -15,18 +15,19 @@ The [Signal CLI REST API](https://github.com/bbernhard/signal-cli-rest-api) prov
 
 It's designed for developers who want to:
 
-- **Restrict** or **log** certain API calls,
-- Enforce **authentication**,
-- Add **templating** or **request preprocessing**,
-- And deploy everything neatly via **Docker**.
+- **Restrict** or **log** certain API calls
+- Enforce **authentication**
+- Add **templating** or **request preprocessing**
+- And deploy everything neatly via **Docker**
 
 ## Key Features
 
-- 🔒 **Access Control** — Protect your Signal API with [**token-based authentication**](./usage#auth) and [**endpoint restrictions**](./features#endpoints).
-- 🧩 **Full Compatibility** — 100% protocol-compatible; all requests are still handled by your existing Signal CLI REST API.
-- ⚙️ **Configurable Proxy Behavior** — Define templates and limits via YAML or environment variables.
-- 🧠 **Message Templates** — Use [**variables**](./configuration/variables) and [**placeholders**](./features#placeholders) to standardize common message formats.
-- 🐳 **Docker-Ready** — Comes packaged for containerized environments, deployable in seconds.
+- 🔒 **Access Control** — Protect your Signal API with [**token-based authentication**](./usage#auth) and [**endpoint restrictions**](./features#endpoints)
+- ⏱️ **Rate Limiting** — [**Limit requests**](./features#rate-limiting) per token to prevent server overload and abuse
+- 🧩 **Full Compatibility** — 100% protocol-compatible; all requests are still handled by your existing Signal CLI REST API
+- ⚙️ **Configurable Proxy Behavior** — Define templates and limits via YAML or environment variables
+- 🧠 **Message Templates** — Use [**variables**](./configuration/variables) and [**placeholders**](./features#placeholders) to standardize common message formats
+- 🐳 **Docker-Ready** — Comes packaged for containerized environments, deployable in seconds
 - [And much more…](./features)
 
 ## Architecture
diff --git a/docs/configuration/ratelimiting.md b/docs/configuration/ratelimiting.md
new file mode 100644
index 00000000..ca13366f
--- /dev/null
+++ b/docs/configuration/ratelimiting.md
@@ -0,0 +1,23 @@
+---
+title: Rate Limiting
+---
+
+# Rate Limiting
+
+Rate limiting is used to control how many requests or actions a token or client can perform within a given period.
+This helps prevent abuse, protect downstream services, and ensure fair usage.
+
+Rate limits can be defined in `settings.access.rateLimiting`:
+
+```yaml
+settings:
+  access:
+    rateLimiting:
+      limit: 100
+      period: 1m
+```
+
+- `limit`: The maximum number of allowed requests in the given period
+- `period`: The duration over which the limit is measured (supports Go duration format like `1m`, `10s`, `1h`)
+
+When a request exceeds the configured rate limit the server responds with `429` `Too Many Requests`.
diff --git a/docs/features/features.md b/docs/features/features.md
index b2166baa..8c003d6d 100644
--- a/docs/features/features.md
+++ b/docs/features/features.md
@@ -48,6 +48,11 @@ This is really helpful when trying to block certain numbers from using certain t
 
 Find more about this feature [here](./configuration/field-policies).
 
+## Rate Limiting
+
+**Rate Limiting** is used for limiting requests and to stop server overload, because of DDoS attacks, malconfigured clients, or malicious actors.  
+It ensures fair usage per token by controlling how many requests can be processed within a defined period.
+
 ## Endpoints
 
 > _Block unwanted access_

From 7da9aa6ee96c881fa61497d8b1e9ed2c396d664b Mon Sep 17 00:00:00 2001
From: CodeShell <122738806+CodeShellDev@users.noreply.github.com>
Date: Sat, 3 Jan 2026 20:22:54 +0100
Subject: [PATCH 2/2] add to config

---
 docs/configuration/examples/config.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/configuration/examples/config.yml b/docs/configuration/examples/config.yml
index 3405163f..d1d83e95 100644
--- a/docs/configuration/examples/config.yml
+++ b/docs/configuration/examples/config.yml
@@ -1,13 +1,12 @@
 # Example Config (all configurations shown)
 service:
   port: 8880
+  logLevel: info
 
 api:
   url: http://signal-api:8080
   tokens: [token1, token2]
 
-logLevel: info
-
 settings:
   message:
     template: |
@@ -28,8 +27,9 @@ settings:
       - "!/v1/about"
       - /v2/send
 
+    rateLimiting:
+      limit: 100
+      period: 1h
+
     fieldPolicies:
-      "@number": {
-        value: "+123400003",
-        action: block
-      }
+      "@number": { value: "+123400003", action: block }