From 8dddadca4e4f02a6ed89ca4cf4d525784caff2d0 Mon Sep 17 00:00:00 2001
From: Marc Littlemore <MarcL@users.noreply.github.com>
Date: Mon, 16 Mar 2026 15:09:44 +0100
Subject: [PATCH] docs: Add manual HashiCorp Vault KV mount configuration
 (#4343)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/external-secrets.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docs/external-secrets.md b/docs/external-secrets.md
index 77d3f5ca3..f3c3ec25b 100644
--- a/docs/external-secrets.md
+++ b/docs/external-secrets.md
@@ -127,6 +127,34 @@ Provide the **Vault URL** for your vault instance, and select your **Authenticat
 	- [Userpass auth method](https://developer.hashicorp.com/vault/docs/auth/userpass)
 - If you use vault namespaces, you can enter the namespace n8n should connect to. Refer to [Vault Enterprise namespaces](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) for more information on HashiCorp Vault namespaces.
 
+#### Manual KV mount configuration
+
+By default, n8n autodiscovers KV secret engines by reading `sys/mounts`. If your Vault token doesn't have access to `sys/mounts`, you can manually specify the KV engine mount path and version instead:
+
+- **KV Mount Path**: The mount path of your KV secret engine (for example, `secret/`). When set, n8n skips `sys/mounts` autodiscovery and uses this path directly. Leave blank to use autodiscovery.
+- **KV Version**: The KV engine version (`v1` or `v2`). Defaults to `v2`. Only applies when you specify a **KV Mount Path**.
+
+Your Vault token still needs read and list access to the KV path itself. The following example shows a minimal Vault policy for a KV v2 mount at `secret/`:
+
+```hcl
+# Read and list secrets at the "secret/" KV v2 mount
+path "secret/data/*" {
+  capabilities = ["read"]
+}
+path "secret/metadata/*" {
+  capabilities = ["read", "list"]
+}
+```
+
+For KV v1, you only need a single policy path:
+
+```hcl
+# Read and list secrets at the "kv/" KV v1 mount
+path "kv/*" {
+  capabilities = ["read", "list"]
+}
+```
+
 ## Share vault
 
 By default, a secrets vault is **global**: users across the instance can use credentials that reference secrets from that vault.