0
# HVAC
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: hvac
7
- **Language**: Python
8
- **Installation**: `pip install hvac`
9

10
## Core Imports
11

12
```python
13
import hvac
14
```
15

16
Primary client class:
17

18
```python
19
from hvac import Client
20
```
21

22
For exception handling:
23

24
```python
25
from hvac import exceptions
26
```
27

28
## Basic Usage
29

30
```python
31
import hvac
32

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

36
# Authenticate with token
37
client.token = 'your-vault-token'
38

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

43
# Basic secret operations
44
# Write a secret
45
client.secrets.kv_v2.create_or_update_secret(
46
    path='myapp/config',
47
    secret={'username': 'admin', 'password': 'secret123'}
48
)
49

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

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

60
## Architecture
61

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

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

69
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.
70

71
## Capabilities
72

73
### Core Client Operations
74

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

77
```python { .api }
78
class Client:
79
    def __init__(
80
        self, 
81
        url: str = None,
82
        token: str = None,
83
        cert: tuple = None,
84
        verify: bool | str = None,
85
        timeout: int = 30,
86
        proxies: dict = None,
87
        allow_redirects: bool = True,
88
        session: requests.Session = None,
89
        adapter: Adapter = None,
90
        namespace: str = None,
91
        **kwargs
92
    ): ...
93
    
94
    def read(self, path: str, wrap_ttl: str = None) -> dict | None: ...
95
    def list(self, path: str) -> dict | None: ...
96
    def write(self, *args, **kwargs) -> dict: ...
97
    def write_data(
98
        self, 
99
        path: str, 
100
        *, 
101
        data: dict = None, 
102
        wrap_ttl: str = None
103
    ) -> dict: ...
104
    def delete(self, path: str) -> None: ...
105
    def is_authenticated(self) -> bool: ...
106
    def login(self, url: str, use_token: bool = True, **kwargs) -> dict: ...
107
```
108

109
[Core Client](./client.md)
110

111
### Authentication Methods
112

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

115
```python { .api }
116
class AuthMethods:
117
    @property
118
    def token(self) -> Token: ...
119
    @property
120
    def userpass(self) -> Userpass: ...
121
    @property
122
    def ldap(self) -> Ldap: ...
123
    @property
124
    def aws(self) -> Aws: ...
125
    @property
126
    def azure(self) -> Azure: ...
127
    @property
128
    def gcp(self) -> Gcp: ...
129
    @property
130
    def kubernetes(self) -> Kubernetes: ...
131
    @property
132
    def github(self) -> Github: ...
133
    @property
134
    def jwt(self) -> JWT: ...
135
    @property
136
    def oidc(self) -> OIDC: ...
137
    @property
138
    def approle(self) -> AppRole: ...
139
    @property
140
    def cert(self) -> Cert: ...
141
    @property
142
    def okta(self) -> Okta: ...
143
    @property
144
    def radius(self) -> Radius: ...
145
    @property
146
    def legacy_mfa(self) -> LegacyMfa: ...
147
```
148

149
[Authentication Methods](./auth-methods.md)
150

151
### Secrets Engines
152

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

155
```python { .api }
156
class SecretsEngines:
157
    @property
158
    def kv_v1(self) -> KvV1: ...
159
    @property
160
    def kv_v2(self) -> KvV2: ...
161
    @property
162
    def database(self) -> Database: ...
163
    @property
164
    def pki(self) -> Pki: ...
165
    @property
166
    def transit(self) -> Transit: ...
167
    @property
168
    def aws(self) -> Aws: ...
169
    @property
170
    def azure(self) -> Azure: ...
171
    @property
172
    def gcp(self) -> Gcp: ...
173
    @property
174
    def active_directory(self) -> ActiveDirectory: ...
175
    @property
176
    def ldap(self) -> Ldap: ...
177
    @property
178
    def ssh(self) -> Ssh: ...
179
    @property
180
    def consul(self) -> Consul: ...
181
    @property
182
    def rabbitmq(self) -> RabbitMQ: ...
183
    @property
184
    def identity(self) -> Identity: ...
185
    @property
186
    def transform(self) -> Transform: ...
187
```
188

189
[Secrets Engines](./secrets-engines.md)
190

191
### System Administration
192

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

195
```python { .api }
196
class SystemBackend:
197
    @property
198
    def init(self) -> Init: ...
199
    @property
200
    def seal(self) -> Seal: ...
201
    @property
202
    def auth(self) -> Auth: ...
203
    @property
204
    def mount(self) -> Mount: ...
205
    @property
206
    def policy(self) -> Policy: ...
207
    @property
208
    def policies(self) -> Policies: ...
209
    @property
210
    def audit(self) -> Audit: ...
211
    @property
212
    def lease(self) -> Lease: ...
213
    @property
214
    def capabilities(self) -> Capabilities: ...
215
    @property
216
    def health(self) -> Health: ...
217
    @property
218
    def leader(self) -> Leader: ...
219
    @property
220
    def key(self) -> Key: ...
221
    @property
222
    def namespace(self) -> Namespace: ...
223
    @property
224
    def quota(self) -> Quota: ...
225
    @property
226
    def raft(self) -> Raft: ...
227
    @property
228
    def wrapping(self) -> Wrapping: ...
229
```
230

231
[System Administration](./system-backend.md)
232

233
## Exception Handling
234

235
```python { .api }
236
class VaultError(Exception):
237
    def __init__(
238
        self,
239
        message: str = None,
240
        errors: list = None,
241
        method: str = None,
242
        url: str = None,
243
        text: str = None,
244
        json: dict = None
245
    ): ...
246

247
class InvalidRequest(VaultError): ...  # 400
248
class Unauthorized(VaultError): ...    # 401  
249
class Forbidden(VaultError): ...       # 403
250
class InvalidPath(VaultError): ...     # 404
251
class UnsupportedOperation(VaultError): ... # Unsupported operation
252
class PreconditionFailed(VaultError): ... # Precondition failed
253
class RateLimitExceeded(VaultError): ... # 429
254
class InternalServerError(VaultError): ... # 500
255
class VaultNotInitialized(VaultError): ... # 501
256
class BadGateway(VaultError): ...      # 502
257
class VaultDown(VaultError): ...       # 503
258
class UnexpectedError(VaultError): ...
259
class ParamValidationError(VaultError): ...
260
```
261

262
## Core Types
263

264
```python { .api }
265
# HTTP Adapters
266
class Adapter:
267
    def __init__(
268
        self,
269
        base_uri: str,
270
        token: str = None,
271
        cert: tuple = None,
272
        verify: bool | str = True,
273
        timeout: int = 30,
274
        proxies: dict = None,
275
        allow_redirects: bool = True,
276
        session: requests.Session = None,
277
        namespace: str = None,
278
        **kwargs
279
    ): ...
280

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

284
# Client Properties  
285
ClientStatus = dict  # Status information dictionaries
286
SecretData = dict    # Secret data structures
287
PolicyDocument = str # HCL policy documents
288
```