Implementation:BerriAI Litellm HashiCorp Secret Manager

Attribute	Value
Sources	litellm/secret_managers/hashicorp_secret_manager.py
Domains	Secret Management, HashiCorp Vault, KV V2, Enterprise
last_updated	2026-02-15 16:00 GMT

Overview

The HashiCorp Secret Manager module integrates HashiCorp Vault's KV v2 secrets engine as a secret management backend for LiteLLM, supporting token, AppRole, and TLS certificate authentication methods.

Description

This module provides the HashicorpSecretManager class, which extends BaseSecretManager to implement full CRUD operations against a HashiCorp Vault KV v2 secrets engine. The class supports three authentication methods in priority order: (1) AppRole authentication via HCP_VAULT_APPROLE_ROLE_ID and HCP_VAULT_APPROLE_SECRET_ID, (2) TLS certificate authentication via HCP_VAULT_CLIENT_CERT and HCP_VAULT_CLIENT_KEY, and (3) direct token authentication via HCP_VAULT_TOKEN. URLs are constructed following KV v2 conventions: {VAULT_ADDR}/v1/{namespace}/{mount}/data/{path_prefix}/{secret_name}. The class includes configurable namespace, mount name, and path prefix support. Secrets are stored under the "key" data field by default (configurable via optional_params). Results are cached in an InMemoryCache with a configurable refresh interval. The async_rotate_secret method performs verified rotation: it checks the old secret exists, writes the new secret, verifies the written value matches, then optionally deletes the old secret. This is a premium/enterprise feature.

Usage

Import and instantiate HashicorpSecretManager when configuring the LiteLLM proxy with key_management_system: hashicorp_vault. Requires environment variables for Vault connection settings.

Code Reference

Source Location

litellm/secret_managers/hashicorp_secret_manager.py

Class: HashicorpSecretManager

class HashicorpSecretManager(BaseSecretManager):
    def __init__(self):

Key Methods

Method	Signature	Description
_verify_required_credentials_exist	def _verify_required_credentials_exist(self) -> None	Validates at least one authentication method is configured
_auth_via_approle	def _auth_via_approle(self) -> str	Authenticates via AppRole and returns a Vault token; caches by lease duration
_auth_via_tls_cert	def _auth_via_tls_cert(self) -> str	Authenticates via TLS certificate and returns a Vault token; caches by lease duration
get_url	def get_url(self, secret_name, namespace=None, mount_name=None, path_prefix=None) -> str	Constructs the Vault KV v2 URL with optional namespace, mount, and path prefix
_get_request_headers	def _get_request_headers(self) -> dict	Returns headers with X-Vault-Token using the appropriate auth method
async_read_secret	async def async_read_secret(self, secret_name, optional_params=None, timeout=None) -> Optional[str]	Reads a secret from Vault KV v2 asynchronously with caching
sync_read_secret	def sync_read_secret(self, secret_name, optional_params=None, timeout=None) -> Optional[str]	Reads a secret from Vault KV v2 synchronously with caching
async_write_secret	async def async_write_secret(self, secret_name, secret_value, description=None, optional_params=None, timeout=None, tags=None) -> Dict[str, Any]	Writes a secret to Vault KV v2 under the configured data key
async_rotate_secret	async def async_rotate_secret(self, current_secret_name, new_secret_name, new_secret_value, optional_params=None, timeout=None) -> Dict	Verified rotation: write new, verify, optionally delete old
async_delete_secret	async def async_delete_secret(self, secret_name, recovery_window_in_days=7, optional_params=None, timeout=None) -> dict	Marks the latest version as deleted in KV v2

Import

from litellm.secret_managers.hashicorp_secret_manager import HashicorpSecretManager

Environment Variables

Variable	Description	Default
HCP_VAULT_ADDR	Vault server address	http://127.0.0.1:8200
HCP_VAULT_TOKEN	Direct Vault token (priority 3)	(empty)
HCP_VAULT_NAMESPACE	Vault namespace	(none)
HCP_VAULT_MOUNT_NAME	KV engine mount name	secret
HCP_VAULT_PATH_PREFIX	Path prefix for secrets	(none)
HCP_VAULT_APPROLE_ROLE_ID	AppRole role ID (priority 1)	(empty)
HCP_VAULT_APPROLE_SECRET_ID	AppRole secret ID (priority 1)	(empty)
HCP_VAULT_APPROLE_MOUNT_PATH	AppRole auth mount path	approle
HCP_VAULT_CLIENT_CERT	TLS client certificate path (priority 2)	(empty)
HCP_VAULT_CLIENT_KEY	TLS client key path (priority 2)	(empty)
HCP_VAULT_CERT_ROLE	TLS cert role name	(none)
HCP_VAULT_REFRESH_INTERVAL	Cache refresh interval in seconds	SECRET_MANAGER_REFRESH_INTERVAL

I/O Contract

Inputs (async_read_secret)

Parameter	Type	Description
secret_name	str	Path inside the KV mount (e.g., "myapp/config")
optional_params	Optional[dict]	Can contain namespace, mount, path_prefix, data overrides
timeout	Optional[Union[float, httpx.Timeout]]	Request timeout

Outputs (async_read_secret)

Return Type	Description
Optional[str]	The secret value from data.data.key in the Vault response, or None on error

Usage Examples

import os
os.environ["HCP_VAULT_ADDR"] = "https://vault.example.com:8200"
os.environ["HCP_VAULT_TOKEN"] = "hvs.CAESI..."

from litellm.secret_managers.hashicorp_secret_manager import HashicorpSecretManager

manager = HashicorpSecretManager()

# Read a secret
value = await manager.async_read_secret("myapp/openai-key")
# Reads from: https://vault.example.com:8200/v1/secret/data/myapp/openai-key
# Returns data.data.key from the JSON response

# Write a secret
result = await manager.async_write_secret(
    secret_name="myapp/new-key",
    secret_value="sk-abc123",
    description="New OpenAI API key",
)

# Rotate a secret with a different name
result = await manager.async_rotate_secret(
    current_secret_name="myapp/old-key",
    new_secret_name="myapp/new-key",
    new_secret_value="sk-new-value",
)

# Read with custom namespace and mount
value = await manager.async_read_secret(
    "mykey",
    optional_params={
        "secret_manager_settings": {
            "namespace": "team-a",
            "mount": "kv",
            "path_prefix": "production",
        }
    },
)

Related Pages

• BerriAI_Litellm_Base_Secret_Manager - Abstract base class this implementation extends
• BerriAI_Litellm_AWS_Secret_Manager_V2 - Alternative secret manager (AWS Secrets Manager)
• BerriAI_Litellm_CyberArk_Secret_Manager - Alternative enterprise secret manager (CyberArk Conjur)
• BerriAI_Litellm_Secret_Manager_Main - Main dispatcher that delegates to this class