0
# Synchronous Secret Operations
1

2
Complete synchronous client for managing Azure Key Vault secrets with blocking operations suitable for traditional Python applications. Provides full CRUD operations, versioning, backup/restore, and soft-delete capabilities.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Create a SecretClient instance for synchronous secret operations with Azure authentication.
9

10
```python { .api }
11
class SecretClient:
12
    def __init__(
13
        self,
14
        vault_url: str,
15
        credential: TokenCredential,
16
        *,
17
        api_version: Optional[Union[ApiVersion, str]] = None,
18
        verify_challenge_resource: bool = True,
19
        **kwargs
20
    ):
21
        """
22
        Initialize a SecretClient for synchronous operations.
23

24
        Parameters:
25
        - vault_url (str): URL of the Azure Key Vault (e.g., "https://vault.vault.azure.net/")
26
        - credential (TokenCredential): Authentication credential from azure.identity
27
        - api_version (ApiVersion | str, optional): API version to use (default: ApiVersion.V7_6)
28
        - verify_challenge_resource (bool, optional): Whether to verify challenge resource (default: True)
29
        """
30
```
31

32
### Basic Secret Operations
33

34
Core operations for creating, retrieving, and updating secrets.
35

36
```python { .api }
37
def get_secret(
38
    self,
39
    name: str,
40
    version: Optional[str] = None,
41
    **kwargs
42
) -> KeyVaultSecret:
43
    """
44
    Get a secret by name and optional version.
45

46
    Parameters:
47
    - name (str): Name of the secret
48
    - version (str, optional): Version of the secret. If not specified, gets the latest version
49

50
    Returns:
51
    KeyVaultSecret: The complete secret including value and properties
52

53
    Raises:
54
    ResourceNotFoundError: Secret does not exist
55
    ClientAuthenticationError: Authentication failed
56
    """
57

58
def set_secret(
59
    self,
60
    name: str,
61
    value: str,
62
    *,
63
    enabled: Optional[bool] = None,
64
    tags: Optional[Dict[str, str]] = None,
65
    content_type: Optional[str] = None,
66
    not_before: Optional[datetime] = None,
67
    expires_on: Optional[datetime] = None,
68
    **kwargs
69
) -> KeyVaultSecret:
70
    """
71
    Create or update a secret.
72

73
    Parameters:
74
    - name (str): Name of the secret
75
    - value (str): Value of the secret
76
    - enabled (bool, optional): Whether the secret is enabled
77
    - tags (Dict[str, str], optional): User-defined metadata
78
    - content_type (str, optional): Content type of the secret
79
    - not_before (datetime, optional): Not valid before date
80
    - expires_on (datetime, optional): Expiration date
81

82
    Returns:
83
    KeyVaultSecret: The created or updated secret
84
    """
85

86
def update_secret_properties(
87
    self,
88
    name: str,
89
    version: Optional[str] = None,
90
    *,
91
    enabled: Optional[bool] = None,
92
    tags: Optional[Dict[str, str]] = None,
93
    content_type: Optional[str] = None,
94
    not_before: Optional[datetime] = None,
95
    expires_on: Optional[datetime] = None,
96
    **kwargs
97
) -> SecretProperties:
98
    """
99
    Update secret metadata without changing the value.
100

101
    Parameters:
102
    - name (str): Name of the secret
103
    - version (str, optional): Version to update. If not specified, updates latest version
104
    - enabled (bool, optional): Whether the secret is enabled
105
    - tags (Dict[str, str], optional): User-defined metadata
106
    - content_type (str, optional): Content type of the secret
107
    - not_before (datetime, optional): Not valid before date
108
    - expires_on (datetime, optional): Expiration date
109

110
    Returns:
111
    SecretProperties: Updated secret properties
112
    """
113
```
114

115
### Listing Operations
116

117
Operations for discovering secrets and their versions.
118

119
```python { .api }
120
def list_properties_of_secrets(
121
    self,
122
    **kwargs
123
) -> ItemPaged[SecretProperties]:
124
    """
125
    List properties of all secrets in the vault.
126

127
    Returns:
128
    ItemPaged[SecretProperties]: Iterator of secret properties (no values)
129
    """
130

131
def list_properties_of_secret_versions(
132
    self,
133
    name: str,
134
    **kwargs
135
) -> ItemPaged[SecretProperties]:
136
    """
137
    List all versions of a specific secret.
138

139
    Parameters:
140
    - name (str): Name of the secret
141

142
    Returns:
143
    ItemPaged[SecretProperties]: Iterator of secret version properties
144
    """
145
```
146

147
### Backup and Restore Operations
148

149
Operations for backing up and restoring secrets for data protection and migration.
150

151
```python { .api }
152
def backup_secret(
153
    self,
154
    name: str,
155
    **kwargs
156
) -> bytes:
157
    """
158
    Backup a secret for external storage or migration.
159

160
    Parameters:
161
    - name (str): Name of the secret to backup
162

163
    Returns:
164
    bytes: Encrypted backup data
165

166
    Raises:
167
    ResourceNotFoundError: Secret does not exist
168
    """
169

170
def restore_secret_backup(
171
    self,
172
    backup: bytes,
173
    **kwargs
174
) -> SecretProperties:
175
    """
176
    Restore a secret from backup data.
177

178
    Parameters:
179
    - backup (bytes): Encrypted backup data from backup_secret()
180

181
    Returns:
182
    SecretProperties: Properties of the restored secret
183

184
    Raises:
185
    ResourceExistsError: Secret already exists
186
    """
187
```
188

189
### Deletion and Recovery Operations
190

191
Soft-delete operations with recovery capabilities for data protection.
192

193
```python { .api }
194
def begin_delete_secret(
195
    self,
196
    name: str,
197
    **kwargs
198
) -> LROPoller[DeletedSecret]:
199
    """
200
    Delete a secret (soft delete with recovery option).
201

202
    Parameters:
203
    - name (str): Name of the secret to delete
204

205
    Returns:
206
    LROPoller[DeletedSecret]: Long-running operation poller
207

208
    Note:
209
    This is a long-running operation. Use poller.result() to wait for completion.
210
    """
211

212
def get_deleted_secret(
213
    self,
214
    name: str,
215
    **kwargs
216
) -> DeletedSecret:
217
    """
218
    Get information about a deleted secret.
219

220
    Parameters:
221
    - name (str): Name of the deleted secret
222

223
    Returns:
224
    DeletedSecret: Information about the deleted secret including recovery details
225
    """
226

227
def list_deleted_secrets(
228
    self,
229
    **kwargs
230
) -> ItemPaged[DeletedSecret]:
231
    """
232
    List all deleted secrets that can be recovered.
233

234
    Returns:
235
    ItemPaged[DeletedSecret]: Iterator of deleted secrets
236
    """
237

238
def purge_deleted_secret(
239
    self,
240
    name: str,
241
    **kwargs
242
) -> None:
243
    """
244
    Permanently delete a secret (cannot be recovered).
245

246
    Parameters:
247
    - name (str): Name of the deleted secret to purge
248

249
    Warning:
250
    This operation is irreversible.
251
    """
252

253
def begin_recover_deleted_secret(
254
    self,
255
    name: str,
256
    **kwargs
257
) -> LROPoller[SecretProperties]:
258
    """
259
    Recover a deleted secret.
260

261
    Parameters:
262
    - name (str): Name of the deleted secret to recover
263

264
    Returns:
265
    LROPoller[SecretProperties]: Long-running operation poller
266
    """
267
```
268

269
### Client Management
270

271
Operations for managing the client lifecycle and custom requests.
272

273
```python { .api }
274
def close(self) -> None:
275
    """
276
    Close the client and clean up resources.
277
    """
278

279
def send_request(
280
    self,
281
    request: HttpRequest,
282
    *,
283
    stream: bool = False,
284
    **kwargs
285
) -> HttpResponse:
286
    """
287
    Send a custom HTTP request using the client's pipeline.
288

289
    Parameters:
290
    - request (HttpRequest): The request to send
291
    - stream (bool, optional): Whether to stream the response
292

293
    Returns:
294
    HttpResponse: The HTTP response
295
    """
296
```
297

298
### Context Manager Support
299

300
Use SecretClient as a context manager for automatic resource cleanup.
301

302
```python { .api }
303
def __enter__(self) -> SecretClient: ...
304
def __exit__(self, *args) -> None: ...
305
```
306

307
### Properties
308

309
```python { .api }
310
@property
311
def vault_url(self) -> str:
312
    """The URL of the Key Vault."""
313
```
314

315
## Usage Examples
316

317
### Complete Secret Lifecycle
318

319
```python
320
from azure.keyvault.secrets import SecretClient
321
from azure.identity import DefaultAzureCredential
322
import datetime
323

324
credential = DefaultAzureCredential()
325
client = SecretClient("https://vault.vault.azure.net/", credential)
326

327
# Create a secret with metadata
328
secret = client.set_secret(
329
    "api-key",
330
    "secret-api-key-value",
331
    enabled=True,
332
    tags={"environment": "production", "service": "api"},
333
    content_type="text/plain",
334
    expires_on=datetime.datetime(2025, 12, 31)
335
)
336

337
# Retrieve the secret
338
retrieved = client.get_secret("api-key")
339
print(f"Secret value: {retrieved.value}")
340

341
# Update metadata without changing value
342
client.update_secret_properties(
343
    "api-key",
344
    tags={"environment": "production", "service": "api", "updated": "true"}
345
)
346

347
# List all secrets
348
for props in client.list_properties_of_secrets():
349
    print(f"Secret: {props.name}, Enabled: {props.enabled}")
350

351
# Backup the secret
352
backup_data = client.backup_secret("api-key")
353

354
# Delete and recover
355
delete_poller = client.begin_delete_secret("api-key")
356
deleted_secret = delete_poller.result()
357

358
recover_poller = client.begin_recover_deleted_secret("api-key")
359
recovered_props = recover_poller.result()
360
```
361

362
### Using Context Manager
363

364
```python
365
from azure.keyvault.secrets import SecretClient
366
from azure.identity import DefaultAzureCredential
367

368
credential = DefaultAzureCredential()
369

370
with SecretClient("https://vault.vault.azure.net/", credential) as client:
371
    # Client automatically closed when exiting context
372
    secret = client.set_secret("temp-secret", "temporary-value")
373
    value = client.get_secret("temp-secret").value
374
```
375

376
## Required Imports
377

378
```python { .api }
379
from typing import Dict, Optional, Union
380
from datetime import datetime
381
from azure.core.polling import LROPoller
382
from azure.core.paging import ItemPaged
383
from azure.core.credentials import TokenCredential
384
from azure.core import HttpRequest, HttpResponse
385
from azure.keyvault.secrets import (
386
    SecretClient,
387
    KeyVaultSecret,
388
    SecretProperties, 
389
    DeletedSecret,
390
    KeyVaultSecretIdentifier,
391
    ApiVersion
392
)
393
```