azure.keyvault.secrets.aio package¶

class azure.keyvault.secrets.aio.SecretClient(vault_url: str, credential: TokenCredential, **kwargs: Any)[source]¶

A high-level asynchronous interface for managing a vault’s secrets.

Parameters

vault_url (str) – URL of the vault the client will access
credential – An object which can provide an access token for the vault, such as a credential from azure.identity.aio

Keyword Arguments

api_version (str) – version of the Key Vault API to use. Defaults to the most recent.
transport (AsyncHttpTransport) – transport to use. Defaults to AioHttpTransport.

Example

Create a new SecretClient¶

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

# Create a SecretClient using default Azure credentials
credentials = DefaultAzureCredential()
secret_client = SecretClient(vault_url, credentials)

async backup_secret(name: str, **kwargs: Any) → bytes[source]¶

Back up a secret in a protected form useable only by Azure Key Vault. Requires secrets/backup permission.

Parameters

name (str) – Name of the secret

Return type

bytes

Raises

ResourceNotFoundError if the secret doesn’t exist, HttpResponseError for other errors

Example:

Back up a secret¶

# backup secret
secret_backup = await secret_client.backup_secret(secret_name)

# returns the raw bytes of the backed up secret
print(secret_backup)

async delete_secret(name: str, **kwargs: Any) → azure.keyvault.secrets._models.DeletedSecret[source]¶

Delete all versions of a secret. Requires secrets/delete permission.

If the vault has soft-delete enabled, deletion may take several seconds to complete.

Return type: DeletedSecret
Raises: ResourceNotFoundError if the secret doesn’t exist, HttpResponseError for other errors

Example

Delete a secret¶

# delete a secret
deleted_secret = await secret_client.delete_secret("secret-name")

print(deleted_secret.name)

# if the vault has soft-delete enabled, the secret's deleted_date,
# scheduled purge date and recovery id are set
print(deleted_secret.deleted_date)
print(deleted_secret.scheduled_purge_date)
print(deleted_secret.recovery_id)

async get_deleted_secret(name: str, **kwargs: Any) → azure.keyvault.secrets._models.DeletedSecret[source]¶

Get a deleted secret. Possible only in vaults with soft-delete enabled. Requires secrets/get permission.

Parameters: name (str) – Name of the deleted secret
Return type: DeletedSecret
Raises: ResourceNotFoundError if the deleted secret doesn’t exist, HttpResponseError for other errors

Example

Get a deleted secret¶

# gets a deleted secret (requires soft-delete enabled for the vault)
deleted_secret = await secret_client.get_deleted_secret("secret-name")
print(deleted_secret.name)

async get_secret(name: str, version: Optional[str] = None, **kwargs: Any) → azure.keyvault.secrets._models.KeyVaultSecret[source]¶

Get a secret. Requires the secrets/get permission.

Parameters

name (str) – The name of the secret
version (str) – (optional) Version of the secret to get. If unspecified, gets the latest version.

Return type

KeyVaultSecret

Raises

ResourceNotFoundError if the secret doesn’t exist, HttpResponseError for other errors

Example

Get a secret¶

# get the latest version of a secret
secret = await secret_client.get_secret("secret-name")

# alternatively, specify a version
secret = await secret_client.get_secret("secret-name", secret_version)

print(secret.id)
print(secret.name)
print(secret.properties.version)
print(secret.properties.vault_url)

list_deleted_secrets(**kwargs: Any) → AsyncIterable[azure.keyvault.secrets._models.DeletedSecret][source]¶

Lists all deleted secrets. Possible only in vaults with soft-delete enabled.

Requires secrets/list permission.

Returns: An iterator of deleted secrets, excluding their values
Return type: AsyncItemPaged[DeletedSecret]

Example

Lists deleted secrets¶

# gets a list of deleted secrets (requires soft-delete enabled for the vault)
deleted_secrets = secret_client.list_deleted_secrets()

async for secret in deleted_secrets:
    # the list doesn't include values or versions of the deleted secrets
    print(secret.id)
    print(secret.name)
    print(secret.scheduled_purge_date)
    print(secret.recovery_id)
    print(secret.deleted_date)

list_properties_of_secret_versions(name: str, **kwargs: Any) → AsyncIterable[azure.keyvault.secrets._models.SecretProperties][source]¶

List properties of all versions of a secret, excluding their values. Requires secrets/list permission.

List items don’t include secret values. Use get_secret() to get a secret’s value.

Parameters: name (str) – Name of the secret
Returns: An iterator of secrets, excluding their values
Return type: AsyncItemPaged[SecretProperties]

Example

List all versions of a secret¶

# gets a list of all versions of a secret
secret_versions = secret_client.list_properties_of_secret_versions("secret-name")

async for secret in secret_versions:
    # the list doesn't include the versions' values
    print(secret.id)
    print(secret.enabled)
    print(secret.updated_on)

list_properties_of_secrets(**kwargs: Any) → AsyncIterable[azure.keyvault.secrets._models.SecretProperties][source]¶

List identifiers and attributes of all secrets in the vault. Requires secrets/list permission.

List items don’t include secret values. Use get_secret() to get a secret’s value.

Returns: An iterator of secrets
Return type: AsyncItemPaged[SecretProperties]

Example

Lists all secrets¶

# gets a list of secrets in the vault
secrets = secret_client.list_properties_of_secrets()

async for secret in secrets:
    # the list doesn't include values or versions of the secrets
    print(secret.id)
    print(secret.name)
    print(secret.enabled)

async purge_deleted_secret(name: str, **kwargs: Any) → None[source]¶

Permanently delete a deleted secret. Possible only in vaults with soft-delete enabled.

If the vault doesn’t have soft-delete enabled, delete_secret() is permanent, and this method will raise an error.

Requires secrets/purge permission.

Parameters: name (str) – Name of the deleted secret to purge
Returns: None
Raises: HttpResponseError

Example

# if the vault has soft-delete enabled, purge permanently deletes the secret
# (with soft-delete disabled, delete_secret is permanent)
await secret_client.purge_deleted_secret("secret-name")

async recover_deleted_secret(name: str, **kwargs: Any) → azure.keyvault.secrets._models.SecretProperties[source]¶

Recover a deleted secret to its latest version. This is possible only in vaults with soft-delete enabled.

If the vault does not have soft-delete enabled, delete_secret() is permanent, and this method will raise an error. Attempting to recover a non-deleted secret will also raise an error.

Requires the secrets/recover permission.

Parameters: name (str) – Name of the deleted secret to recover
Return type: SecretProperties
Raises: HttpResponseError

Example

Recover a deleted secret¶

# recover deleted secret to the latest version
recovered_secret = await secret_client.recover_deleted_secret("secret-name")
print(recovered_secret.id)
print(recovered_secret.name)

async restore_secret_backup(backup: bytes, **kwargs: Any) → azure.keyvault.secrets._models.SecretProperties[source]¶

Restore a backed up secret. Requires the secrets/restore permission.

Parameters: backup (bytes) – A secret backup as returned by backup_secret()
Returns: The restored secret
Return type: SecretProperties
Raises: ResourceExistsError if the secret’s name is already in use, HttpResponseError for other errors

Example

Restore a backed up secret¶

# restores a backed up secret
restored_secret = await secret_client.restore_secret_backup(secret_backup)
print(restored_secret.id)
print(restored_secret.version)

async set_secret(name: str, value: str, **kwargs: Any) → azure.keyvault.secrets._models.KeyVaultSecret[source]¶

Set a secret value. If name is in use, create a new version of the secret. If not, create a new secret.

Requires secrets/set permission.

Parameters

name (str) – The name of the secret
value (str) – The value of the secret

Keyword Arguments

enabled (bool) – Whether the secret is enabled for use.
tags (dict[str, str]) – Application specific metadata in the form of key-value pairs.
content_type (str) – An arbitrary string indicating the type of the secret, e.g. ‘password’
not_before (datetime) – Not before date of the secret in UTC
expires_on (datetime) – Expiry date of the secret in UTC

Return type

KeyVaultSecret

Raises

HttpResponseError

Example

Set a secret’s value¶

from dateutil import parser as date_parse

expires_on = date_parse.parse("2050-02-02T08:00:00.000Z")

# create a secret, setting optional arguments
secret = await secret_client.set_secret("secret-name", "secret-value", enabled=True, expires_on=expires_on)

print(secret.id)
print(secret.name)
print(secret.properties.enabled)
print(secret.properties.expires_on)

async update_secret_properties(name: str, version: Optional[str] = None, **kwargs: Any) → azure.keyvault.secrets._models.SecretProperties[source]¶

Update properties of a secret other than its value. Requires secrets/set permission.

This method updates properties of the secret, such as whether it’s enabled, but can’t change the secret’s value. Use set_secret() to change the secret’s value.

Parameters

name (str) – Name of the secret
version (str) – (optional) Version of the secret to update. If unspecified, the latest version is updated.

Keyword Arguments

enabled (bool) – Whether the secret is enabled for use.
tags (dict[str, str]) – Application specific metadata in the form of key-value pairs.
content_type (str) – An arbitrary string indicating the type of the secret, e.g. ‘password’
not_before (datetime) – Not before date of the secret in UTC
expires_on (datetime) – Expiry date of the secret in UTC

Return type

SecretProperties

Raises

ResourceNotFoundError if the secret doesn’t exist, HttpResponseError for other errors

Example

Updates a secret’s attributes¶

# update attributes of an existing secret
content_type = "text/plain"
tags = {"foo": "updated tag"}
updated_secret_properties = await secret_client.update_secret_properties(
    "secret-name", content_type=content_type, tags=tags
)

print(updated_secret_properties.version)
print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.tags)

property vault_url¶