From 86875bcc59ef7f672470e34f1d90ba98bcb5dcb1 Mon Sep 17 00:00:00 2001
From: James P <jamesperkins@hey.com>
Date: Thu, 22 Jan 2026 14:31:40 -0500
Subject: [PATCH] docs: add Unkey rate limiting setup documentation (#27163)

- Update .env.example with clarified Unkey configuration comments
- Update README.md with explainer of Unkey and how it's optional.
---
 .env.example |  5 ++++-
 README.md    | 13 +++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/.env.example b/.env.example
index 019cfef8d6..a2e9e7c65b 100644
--- a/.env.example
+++ b/.env.example
@@ -398,7 +398,10 @@ NEXT_PUBLIC_API_V2_URL="http://localhost:5555/api/v2"
 TASKER_ENABLE_WEBHOOKS=0
 TASKER_ENABLE_EMAILS=0
 
-# Ratelimiting via unkey
+# Ratelimiting via Unkey (https://unkey.com)
+# Optional: Only required if you want to enable rate limiting
+# Not needed for testing or self-hosting unless you specifically want rate limiting features
+# Sign up at https://unkey.com to get your Root key
 UNKEY_ROOT_KEY=
 
 # Used for Cal.ai Voice AI Agents
diff --git a/README.md b/README.md
index c0f2a38270..30058f4264 100644
--- a/README.md
+++ b/README.md
@@ -888,6 +888,19 @@ following
 
 [Follow these steps](./packages/app-store/pipedrive-crm/)
 
+### Rate Limiting with Unkey
+
+Cal.com uses [Unkey](https://unkey.com) for rate limiting. This is an optional feature and is not required for testing or self-hosting.
+
+If you want to enable rate limiting:
+
+1. Sign up for an account at [unkey.com](https://unkey.com)
+2. Create a Root key with permissions for 
+   `ratelimit.create_namespace` and `ratelimit.limit`
+3. Copy the root key to your `.env` file into the `UNKEY_ROOT_KEY` field
+
+Note: If you don't configure Unkey, Cal.com will work normally without rate limiting enabled.
+
 ## Workflows
 
 ### Setting up SendGrid for Email reminders