KV v1/v2 Behavior

vault-kv-client works with both KV v1 and KV v2.

Version Detection

• If you pass kv_version="1" or kv_version="2", the client uses it directly.
• If you omit kv_version, the client reads the mount configuration and caches the result in memory per mount point.
• If the mount configuration cannot be read, the client falls back to KV v1.

Read Semantics

• KV v2 responses are normalized to return the nested data.data payload.
• KV v1 responses return the top-level data payload.
• Missing paths raise SecretNotFoundError for read operations.

List Semantics

• list_secrets() returns only direct children of the requested prefix.
• list_all_secrets() recursively walks nested folders and returns full paths.
• Missing list paths return an empty list.

Cache Semantics

• Read cache is enabled by default.
• Cache is local to the manager instance.
• upsert_secret() clears the cache after a successful write.
• clear_cache() can be called manually if secrets rotate frequently.