or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

auth-methods.mdclient.mdindex.mdsecrets-engines.mdsystem-backend.md
tile.json

tessl/pypi-hvac

HashiCorp Vault API client for Python with comprehensive authentication, secrets management, and system administration capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/hvac@2.3.x

To install, run

npx @tessl/cli install tessl/pypi-hvac@2.3.0

index.mddocs/

HVAC

A comprehensive Python API client for HashiCorp Vault that provides complete access to Vault's secrets management, authentication, and system administration capabilities. HVAC enables developers to programmatically interact with Vault for secure secret storage, dynamic credential generation, encryption operations, and infrastructure security management.

Package Information

  • Package Name: hvac
  • Language: Python
  • Installation: pip install hvac

Core Imports

import hvac

Primary client class:

from hvac import Client

For exception handling:

from hvac import exceptions

Basic Usage

import hvac

# Initialize client
client = hvac.Client(url='https://vault.example.com:8200')

# Authenticate with token
client.token = 'your-vault-token'

# Verify authentication
if client.is_authenticated():
    print("Successfully authenticated with Vault")

# Basic secret operations
# Write a secret
client.secrets.kv_v2.create_or_update_secret(
    path='myapp/config',
    secret={'username': 'admin', 'password': 'secret123'}
)

# Read a secret
response = client.secrets.kv_v2.read_secret_version(path='myapp/config')
secret_data = response['data']['data']
print(f"Username: {secret_data['username']}")

# List secrets
secrets_list = client.secrets.kv_v2.list_secrets(path='myapp')
print(f"Available secrets: {secrets_list['data']['keys']}")

Architecture

HVAC organizes Vault's extensive API into three main categories:

  • Client Interface: Core client with direct Vault operations and legacy method compatibility
  • Authentication Methods (client.auth): 15+ authentication backends for various identity providers and platforms
  • Secrets Engines (client.secrets): 17+ engines for different secret types, dynamic credentials, and encryption services
  • System Backend (client.sys): Administrative operations for Vault configuration, monitoring, and management

This design provides both high-level convenience methods and complete low-level access to Vault's REST API, supporting everything from simple secret storage to enterprise security automation.

Capabilities

Core Client Operations

Direct Vault operations for reading, writing, and managing secrets with full control over request parameters and response handling.

class Client:
    def __init__(
        self, 
        url: str = None,
        token: str = None,
        cert: tuple = None,
        verify: bool | str = None,
        timeout: int = 30,
        proxies: dict = None,
        allow_redirects: bool = True,
        session: requests.Session = None,
        adapter: Adapter = None,
        namespace: str = None,
        **kwargs
    ): ...
    
    def read(self, path: str, wrap_ttl: str = None) -> dict | None: ...
    def list(self, path: str) -> dict | None: ...
    def write(self, *args, **kwargs) -> dict: ...
    def write_data(
        self, 
        path: str, 
        *, 
        data: dict = None, 
        wrap_ttl: str = None
    ) -> dict: ...
    def delete(self, path: str) -> None: ...
    def is_authenticated(self) -> bool: ...
    def login(self, url: str, use_token: bool = True, **kwargs) -> dict: ...

Core Client

Authentication Methods

Comprehensive authentication backend support including cloud providers, identity systems, and custom authentication flows.

class AuthMethods:
    @property
    def token(self) -> Token: ...
    @property
    def userpass(self) -> Userpass: ...
    @property
    def ldap(self) -> Ldap: ...
    @property
    def aws(self) -> Aws: ...
    @property
    def azure(self) -> Azure: ...
    @property
    def gcp(self) -> Gcp: ...
    @property
    def kubernetes(self) -> Kubernetes: ...
    @property
    def github(self) -> Github: ...
    @property
    def jwt(self) -> JWT: ...
    @property
    def oidc(self) -> OIDC: ...
    @property
    def approle(self) -> AppRole: ...
    @property
    def cert(self) -> Cert: ...
    @property
    def okta(self) -> Okta: ...
    @property
    def radius(self) -> Radius: ...
    @property
    def legacy_mfa(self) -> LegacyMfa: ...

Authentication Methods

Secrets Engines

Dynamic secret generation, static secret storage, encryption services, and credential management for databases, cloud services, and infrastructure components.

class SecretsEngines:
    @property
    def kv_v1(self) -> KvV1: ...
    @property
    def kv_v2(self) -> KvV2: ...
    @property
    def database(self) -> Database: ...
    @property
    def pki(self) -> Pki: ...
    @property
    def transit(self) -> Transit: ...
    @property
    def aws(self) -> Aws: ...
    @property
    def azure(self) -> Azure: ...
    @property
    def gcp(self) -> Gcp: ...
    @property
    def active_directory(self) -> ActiveDirectory: ...
    @property
    def ldap(self) -> Ldap: ...
    @property
    def ssh(self) -> Ssh: ...
    @property
    def consul(self) -> Consul: ...
    @property
    def rabbitmq(self) -> RabbitMQ: ...
    @property
    def identity(self) -> Identity: ...
    @property
    def transform(self) -> Transform: ...

Secrets Engines

System Administration

Complete Vault administration including initialization, seal management, policy administration, audit logging, and cluster operations.

class SystemBackend:
    @property
    def init(self) -> Init: ...
    @property
    def seal(self) -> Seal: ...
    @property
    def auth(self) -> Auth: ...
    @property
    def mount(self) -> Mount: ...
    @property
    def policy(self) -> Policy: ...
    @property
    def policies(self) -> Policies: ...
    @property
    def audit(self) -> Audit: ...
    @property
    def lease(self) -> Lease: ...
    @property
    def capabilities(self) -> Capabilities: ...
    @property
    def health(self) -> Health: ...
    @property
    def leader(self) -> Leader: ...
    @property
    def key(self) -> Key: ...
    @property
    def namespace(self) -> Namespace: ...
    @property
    def quota(self) -> Quota: ...
    @property
    def raft(self) -> Raft: ...
    @property
    def wrapping(self) -> Wrapping: ...

System Administration

Exception Handling

class VaultError(Exception):
    def __init__(
        self,
        message: str = None,
        errors: list = None,
        method: str = None,
        url: str = None,
        text: str = None,
        json: dict = None
    ): ...

class InvalidRequest(VaultError): ...  # 400
class Unauthorized(VaultError): ...    # 401  
class Forbidden(VaultError): ...       # 403
class InvalidPath(VaultError): ...     # 404
class UnsupportedOperation(VaultError): ... # Unsupported operation
class PreconditionFailed(VaultError): ... # Precondition failed
class RateLimitExceeded(VaultError): ... # 429
class InternalServerError(VaultError): ... # 500
class VaultNotInitialized(VaultError): ... # 501
class BadGateway(VaultError): ...      # 502
class VaultDown(VaultError): ...       # 503
class UnexpectedError(VaultError): ...
class ParamValidationError(VaultError): ...

Core Types

# HTTP Adapters
class Adapter:
    def __init__(
        self,
        base_uri: str,
        token: str = None,
        cert: tuple = None,
        verify: bool | str = True,
        timeout: int = 30,
        proxies: dict = None,
        allow_redirects: bool = True,
        session: requests.Session = None,
        namespace: str = None,
        **kwargs
    ): ...

class JSONAdapter(Adapter): ...  # Default adapter with JSON responses
class RawAdapter(Adapter): ...   # Raw HTTP response adapter

# Client Properties  
ClientStatus = dict  # Status information dictionaries
SecretData = dict    # Secret data structures
PolicyDocument = str # HCL policy documents