# azure.keyvault.secrets.aio package

## Submodules

## azure.keyvault.secrets.aio.client module

## Module contents

class `azure.keyvault.secrets.aio.``SecretClient`(vault_url: str, credential: TokenCredential, **kwargs)

  Bases: `azure.keyvault.secrets._shared.async_client_base.AsyncKeyVaultClientBase`

  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)

  `backup_secret`(name: str, **kwargs) → bytes

    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)

  `delete_secret`(name: str, **kwargs) → azure.keyvault.secrets._models.DeletedSecret

    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)

  `get_deleted_secret`(name: str, **kwargs) → azure.keyvault.secrets._models.DeletedSecret

    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)

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

    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) → AsyncIterable[azure.keyvault.secrets._models.DeletedSecret]

    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) → AsyncIterable[azure.keyvault.secrets._models.SecretProperties]

    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) → AsyncIterable[azure.keyvault.secrets._models.SecretProperties]

    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)

  `purge_deleted_secret`(name: str, **kwargs) → None

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

    Performs an irreversible deletion of the specified secret, without possibility for recovery. The operation is not available if the `recovery_level` does not specify ‘Purgeable’. This method is only necessary for purging a secret before its `scheduled_purge_date`.

    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")

  `recover_deleted_secret`(name: str, **kwargs) → azure.keyvault.secrets._models.SecretProperties

    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)

  `restore_secret_backup`(backup: bytes, **kwargs) → azure.keyvault.secrets._models.SecretProperties

    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)

  `set_secret`(name: str, value: str, **kwargs) → azure.keyvault.secrets._models.KeyVaultSecret

    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)

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

    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)