From c0d6d7f641646ef5109ce8495535de5b9fd0b24a Mon Sep 17 00:00:00 2001
From: Johannes Battjes <johannes.battjes@roxit.nl>
Date: Thu, 26 Mar 2026 08:56:06 +0100
Subject: [PATCH 1/2] bsn

---
 docs/cases/use-of-bsn.md | 47 ++++++++++++++++++++++++++++++++++++++++
 sidebars.ts              | 18 +++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 docs/cases/use-of-bsn.md

diff --git a/docs/cases/use-of-bsn.md b/docs/cases/use-of-bsn.md
new file mode 100644
index 0000000..3bf77c9
--- /dev/null
+++ b/docs/cases/use-of-bsn.md
@@ -0,0 +1,47 @@
+---
+id: use-of-bsn
+title: Use of BSN (social security number)
+---
+
+For developers and information analysts:
+
+Retrieving cases using a BSN (Dutch Social Security Number) can be done in two ways. While our case registration software supports both methods, many client applications are still using an older, insecure method. This article explains the problem and the recommended solution.
+
+### The Problem: Leaking BSNs via GET Requests
+
+The current, widely-used method for fetching cases by BSN is a `GET` request where the BSN is passed as a URL parameter:
+
+```h
+ttps://zaken.preprod-rx-services.nl/api/v1/zaken?rol__betrokkeneIdentificatie__natuurlijkPersoon__inpBsn=123443210&expand=status.statusType
+```
+
+**This is a security and privacy risk.**
+
+The BSN is sensitive, personal data. Placing it in a URL has serious consequences:
+
+- **Extensive Logging**: Web servers, proxies, load balancers, and other network infrastructure log URLs by default. This means the BSN is stored in numerous log files across different systems.
+- **Increased Exposure**: These logs are often retained for long periods and accessed for monitoring, debugging, or analytics, exposing the BSN to a wider audience than necessary.
+- **Privacy Violation**: Unnecessarily logging sensitive data violates fundamental privacy principles (like GDPR/AVG) and creates a data leak that is difficult to contain or audit.
+
+### The Solution: Use POST `/_zoek`
+
+A safer and more robust alternative is to use the `POST /_zoek` endpoint from the VNG Zaken API. This method allows you to send the search parameters in the request body instead of the URL.
+
+Since request bodies are generally not logged by servers and proxies, the BSN remains secure and is not exposed in log files.
+
+Here is an example of how to use the `/_zoek` endpoint. Many other attributes are also possible.
+
+**Request:**
+
+```json
+POST /api/v1/zaken/_zoek
+Host: zaken.preprod-rx-services.nl
+Content-Type: application/json
+
+{
+    "rol__betrokkeneIdentificatie__natuurlijkPersoon__inpBsn": "123443210",
+    "expand": "rollen"
+}
+```
+
+We strongly urge developers of client applications to update their implementation to use the `POST /_zoek` method to ensure the privacy and security of citizen data.
diff --git a/sidebars.ts b/sidebars.ts
index dc60dcb..151dfa3 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -98,6 +98,24 @@ const sidebars: SidebarsConfig = {
                     label: "Document Upload Guide"
                 }
             ]
+        },
+        {
+            type: "category",
+            label: "Cases",
+            items: [
+                {
+                    type: "doc",
+                    id: "cases/use-of-bsn",
+                    label: "Use of BSN"
+                }
+            ]
+        }
+    ],
+    changelog: [
+        {
+            type: "doc",
+            id: "changelog",
+            label: "Changelog"
         }
     ]
 };

From e382e103c4ef9a23d9b3ac41964d78544425b22f Mon Sep 17 00:00:00 2001
From: Johannes Battjes <johannes.battjes@roxit.nl>
Date: Thu, 26 Mar 2026 09:03:05 +0100
Subject: [PATCH 2/2] a

---
 docs/cases/use-of-bsn.md | 8 +++-----
 sidebars.ts              | 7 -------
 2 files changed, 3 insertions(+), 12 deletions(-)

diff --git a/docs/cases/use-of-bsn.md b/docs/cases/use-of-bsn.md
index 3bf77c9..e48fd1b 100644
--- a/docs/cases/use-of-bsn.md
+++ b/docs/cases/use-of-bsn.md
@@ -1,18 +1,16 @@
 ---
 id: use-of-bsn
-title: Use of BSN (social security number)
+title: Retrieving cases for a particular BSN
 ---
 
-For developers and information analysts:
-
-Retrieving cases using a BSN (Dutch Social Security Number) can be done in two ways. While our case registration software supports both methods, many client applications are still using an older, insecure method. This article explains the problem and the recommended solution.
+Retrieving cases using a BSN (Dutch Social Security Number) can be done in two ways. While our case registration software supports both methods, many client applications are using the older, insecure method. This article explains the problem and the recommended solution.
 
 ### The Problem: Leaking BSNs via GET Requests
 
 The current, widely-used method for fetching cases by BSN is a `GET` request where the BSN is passed as a URL parameter:
 
 ```h
-ttps://zaken.preprod-rx-services.nl/api/v1/zaken?rol__betrokkeneIdentificatie__natuurlijkPersoon__inpBsn=123443210&expand=status.statusType
+ttps://zaken.preprod-rx-services.nl/api/v1/zaken?rol__betrokkeneIdentificatie__natuurlijkPersoon__inpBsn=123443210
 ```
 
 **This is a security and privacy risk.**
diff --git a/sidebars.ts b/sidebars.ts
index 151dfa3..1009a3d 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -110,13 +110,6 @@ const sidebars: SidebarsConfig = {
                 }
             ]
         }
-    ],
-    changelog: [
-        {
-            type: "doc",
-            id: "changelog",
-            label: "Changelog"
-        }
     ]
 };