From 0542bcca9e91905fdc1028f3ff8dd6b33cbb7670 Mon Sep 17 00:00:00 2001
From: Kim Shalti Aharfi <kim.aharfi@octopus.com>
Date: Tue, 5 May 2026 09:07:16 +0300
Subject: [PATCH] feat: add documentation for Codefresh API keys rate limiter
 under security

---
 _data/nav.yml                           |  2 ++
 _docs/security/api-key-rate-limiting.md | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+)
 create mode 100644 _docs/security/api-key-rate-limiting.md

diff --git a/_data/nav.yml b/_data/nav.yml
index 3b58d4235..1c00e405b 100644
--- a/_data/nav.yml
+++ b/_data/nav.yml
@@ -731,6 +731,8 @@
       url: "/codefresh-signed-artifacts"
     - title: Verify authenticity of artifacts signed with Codefresh pipelines
       url: "/pipelines-verify-cf-artifacts"
+    - title: Codefresh API keys rate limiter
+      url: "/api-key-rate-limiting"
 
 - title: What's new
   url: "/whats-new"
diff --git a/_docs/security/api-key-rate-limiting.md b/_docs/security/api-key-rate-limiting.md
new file mode 100644
index 000000000..156a1ccb3
--- /dev/null
+++ b/_docs/security/api-key-rate-limiting.md
@@ -0,0 +1,18 @@
+---
+title: "Codefresh API keys rate limiter"
+description: "Understand rate limiting behavior for Codefresh API keys"
+group: security
+toc: true
+---
+
+## Codefresh API keys rate limiter
+
+To ensure platform stability and fair usage across all accounts, API requests are subject to rate limiting on a per Codefresh API-key basis.
+
+Specific rate limit thresholds may vary and are subject to change without prior notice.
+
+If your application exceeds the allowed request rate, the API will respond with HTTP status `429 Too Many Requests`.
+
+If access has been restricted for your API key due to unusual activity, the API will respond with HTTP status `403 Forbidden`.
+
+Design your integrations to handle `429` responses gracefully rather than relying on a fixed request budget.