0
# Asynchronous Secret Operations
1

2
Full async client providing non-blocking secret management operations optimized for concurrent workloads and asyncio applications. Supports all secret operations in an asynchronous context with proper async/await patterns.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Create an async SecretClient instance for non-blocking secret operations.
9

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

24
        Parameters:
25
        - vault_url (str): URL of the Azure Key Vault
26
        - credential (AsyncTokenCredential): Async authentication credential
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 Async Secret Operations
33

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

36
```python { .api }
37
async def get_secret(
38
    self,
39
    name: str,
40
    version: Optional[str] = None,
41
    **kwargs
42
) -> KeyVaultSecret:
43
    """
44
    Asynchronously 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
async 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
    Asynchronously 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
async 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
    Asynchronously 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
### Async Listing Operations
116

117
Async operations for discovering secrets and their versions using async iterators.
118

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

127
    Returns:
128
    AsyncItemPaged[SecretProperties]: Async iterator of secret properties (no values)
129
    """
130

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

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

142
    Returns:
143
    AsyncItemPaged[SecretProperties]: Async iterator of secret version properties
144
    """
145
```
146

147
### Async Backup and Restore Operations
148

149
Async operations for backing up and restoring secrets.
150

151
```python { .api }
152
async def backup_secret(
153
    self,
154
    name: str,
155
    **kwargs
156
) -> bytes:
157
    """
158
    Asynchronously 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
async def restore_secret_backup(
171
    self,
172
    backup: bytes,
173
    **kwargs
174
) -> SecretProperties:
175
    """
176
    Asynchronously 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
### Async Deletion and Recovery Operations
190

191
Async soft-delete operations with direct completion (no LRO poller).
192

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

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

205
    Returns:
206
    DeletedSecret: Information about the deleted secret
207

208
    Note:
209
    Unlike the sync client, this handles polling internally and returns the final result.
210
    """
211

212
async def get_deleted_secret(
213
    self,
214
    name: str,
215
    **kwargs
216
) -> DeletedSecret:
217
    """
218
    Asynchronously 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
) -> AsyncItemPaged[DeletedSecret]:
231
    """
232
    Asynchronously list all deleted secrets that can be recovered.
233

234
    Returns:
235
    AsyncItemPaged[DeletedSecret]: Async iterator of deleted secrets
236
    """
237

238
async def purge_deleted_secret(
239
    self,
240
    name: str,
241
    **kwargs
242
) -> None:
243
    """
244
    Asynchronously and 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
async def recover_deleted_secret(
254
    self,
255
    name: str,
256
    **kwargs
257
) -> SecretProperties:
258
    """
259
    Asynchronously recover a deleted secret.
260

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

264
    Returns:
265
    SecretProperties: Properties of the recovered secret
266

267
    Note:
268
    Unlike the sync client, this handles polling internally and returns the final result.
269
    """
270
```
271

272
### Async Client Management
273

274
Async operations for managing the client lifecycle and custom requests.
275

276
```python { .api }
277
async def close(self) -> None:
278
    """
279
    Asynchronously close the client and clean up resources.
280
    """
281

282
def send_request(
283
    self,
284
    request: HttpRequest,
285
    *,
286
    stream: bool = False,
287
    **kwargs
288
) -> Awaitable[AsyncHttpResponse]:
289
    """
290
    Send a custom HTTP request using the client's pipeline.
291

292
    Parameters:
293
    - request (HttpRequest): The request to send
294
    - stream (bool, optional): Whether to stream the response
295

296
    Returns:
297
    Awaitable[AsyncHttpResponse]: Awaitable HTTP response
298
    """
299
```
300

301
### Async Context Manager Support
302

303
Use async SecretClient as an async context manager for automatic resource cleanup.
304

305
```python { .api }
306
async def __aenter__(self) -> SecretClient: ...
307
async def __aexit__(self, *args) -> None: ...
308
```
309

310
### Properties
311

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

318
## Usage Examples
319

320
### Basic Async Operations
321

322
```python
323
import asyncio
324
from azure.keyvault.secrets.aio import SecretClient
325
from azure.identity.aio import DefaultAzureCredential
326

327
async def main():
328
    credential = DefaultAzureCredential()
329
    client = SecretClient("https://vault.vault.azure.net/", credential)
330
    
331
    try:
332
        # Set a secret
333
        secret = await client.set_secret("async-secret", "async-value")
334
        print(f"Created: {secret.name}")
335
        
336
        # Get the secret
337
        retrieved = await client.get_secret("async-secret")
338
        print(f"Value: {retrieved.value}")
339
        
340
        # Delete the secret
341
        deleted = await client.delete_secret("async-secret")
342
        print(f"Deleted: {deleted.name}")
343
        
344
    finally:
345
        await client.close()
346

347
asyncio.run(main())
348
```
349

350
### Using Async Context Manager
351

352
```python
353
import asyncio
354
from azure.keyvault.secrets.aio import SecretClient
355
from azure.identity.aio import DefaultAzureCredential
356

357
async def main():
358
    credential = DefaultAzureCredential()
359
    
360
    async with SecretClient("https://vault.vault.azure.net/", credential) as client:
361
        # Client automatically closed when exiting context
362
        secret = await client.set_secret("temp-secret", "temporary-value")
363
        value = (await client.get_secret("temp-secret")).value
364
        print(f"Secret value: {value}")
365

366
asyncio.run(main())
367
```
368

369
### Concurrent Operations
370

371
```python
372
import asyncio
373
from azure.keyvault.secrets.aio import SecretClient
374
from azure.identity.aio import DefaultAzureCredential
375

376
async def create_secret(client, name, value):
377
    return await client.set_secret(name, value)
378

379
async def main():
380
    credential = DefaultAzureCredential()
381
    
382
    async with SecretClient("https://vault.vault.azure.net/", credential) as client:
383
        # Create multiple secrets concurrently
384
        tasks = [
385
            create_secret(client, f"secret-{i}", f"value-{i}")
386
            for i in range(5)
387
        ]
388
        
389
        secrets = await asyncio.gather(*tasks)
390
        for secret in secrets:
391
            print(f"Created: {secret.name}")
392

393
asyncio.run(main())
394
```
395

396
### Async Iteration
397

398
```python
399
import asyncio
400
from azure.keyvault.secrets.aio import SecretClient
401
from azure.identity.aio import DefaultAzureCredential
402

403
async def main():
404
    credential = DefaultAzureCredential()
405
    
406
    async with SecretClient("https://vault.vault.azure.net/", credential) as client:
407
        # List all secrets asynchronously
408
        async for secret_props in client.list_properties_of_secrets():
409
            print(f"Secret: {secret_props.name}")
410
            
411
        # List versions of a specific secret
412
        async for version_props in client.list_properties_of_secret_versions("my-secret"):
413
            print(f"Version: {version_props.version}")
414

415
asyncio.run(main())
416
```
417

418
### Complete Async Workflow
419

420
```python
421
import asyncio
422
from azure.keyvault.secrets.aio import SecretClient
423
from azure.identity.aio import DefaultAzureCredential
424

425
async def secret_lifecycle(client):
426
    # Create secret
427
    secret = await client.set_secret(
428
        "lifecycle-secret",
429
        "initial-value",
430
        tags={"environment": "test"}
431
    )
432
    
433
    # Update properties
434
    await client.update_secret_properties(
435
        "lifecycle-secret",
436
        tags={"environment": "test", "updated": "true"}
437
    )
438
    
439
    # Backup
440
    backup_data = await client.backup_secret("lifecycle-secret")
441
    
442
    # Delete
443
    await client.delete_secret("lifecycle-secret")
444
    
445
    # Recover
446
    recovered = await client.recover_deleted_secret("lifecycle-secret")
447
    
448
    return recovered
449

450
async def main():
451
    credential = DefaultAzureCredential()
452
    
453
    async with SecretClient("https://vault.vault.azure.net/", credential) as client:
454
        result = await secret_lifecycle(client)
455
        print(f"Lifecycle complete for: {result.name}")
456

457
asyncio.run(main())
458
```
459

460
## Required Imports
461

462
```python { .api }
463
from typing import Dict, Optional, Union, Awaitable
464
from datetime import datetime
465
from azure.core.async_paging import AsyncItemPaged
466
from azure.core.credentials_async import AsyncTokenCredential
467
from azure.core import HttpRequest, AsyncHttpResponse
468
from azure.keyvault.secrets import (
469
    KeyVaultSecret,
470
    SecretProperties, 
471
    DeletedSecret,
472
    KeyVaultSecretIdentifier,
473
    ApiVersion
474
)
475
from azure.keyvault.secrets.aio import SecretClient
476
```