SecretClient Class

Reference

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

Inheritance: azure.keyvault.secrets._shared.client_base.KeyVaultClientBase

SecretClient

Constructor

SecretClient(vault_url: str, credential: TokenCredential, **kwargs: Any)

Parameters

vault_url: str

Required

URL of the vault the client will access. This is also called the vault's "DNS Name".

credential

Required

An object which can provide an access token for the vault, such as a credential from identity

api_version: ApiVersion

version of the Key Vault API to use. Defaults to the most recent.

transport: HttpTransport

transport to use. Defaults to RequestsTransport.

Examples

Create a new SecretClient


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

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

Methods

backup_secret	Back up a secret in a protected form useable only by Azure Key Vault. Requires secrets/backup permission.
begin_delete_secret	Delete all versions of a secret. Requires secrets/delete permission. When this method returns Key Vault has begun deleting the secret. Deletion may take several seconds in a vault with soft-delete enabled. This method therefore returns a poller enabling you to wait for deletion to complete.
begin_recover_deleted_secret	Recover a deleted secret to its latest version. Possible only in a vault with soft-delete enabled. If the vault does not have soft-delete enabled, begin_delete_secret is permanent, and this method will return an error. Attempting to recover a non-deleted secret will also return an error. When this method returns Key Vault has begun recovering the secret. Recovery may take several seconds. This method therefore returns a poller enabling you to wait for recovery to complete. Waiting is only necessary when you want to use the recovered secret in another operation immediately. Requires the secrets/recover permission.
get_deleted_secret	Get a deleted secret. Possible only in vaults with soft-delete enabled. Requires secrets/get permission.
get_secret	Get a secret. Requires the secrets/get permission.
list_deleted_secrets	Lists all deleted secrets. Possible only in vaults with soft-delete enabled. Requires secrets/list permission.
list_properties_of_secret_versions	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.
list_properties_of_secrets	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.
purge_deleted_secret	Permanently deletes 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.
restore_secret_backup	Restore a backed up secret. Requires the secrets/restore permission.
set_secret	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.
update_secret_properties	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.

backup_secret

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

backup_secret(name: str, **kwargs: Any) -> bytes

Parameters

name: str

Required

Name of the secret to back up

Return type

bytes

Exceptions

ResourceNotFoundError

if the secret doesn't exist,

HttpResponseError

for other errors

Examples

Back up a secret


   # backup secret
   # returns the raw bytes of the backed up secret
   secret_backup = secret_client.backup_secret(secret_name)

   print(secret_backup)

begin_delete_secret

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

When this method returns Key Vault has begun deleting the secret. Deletion may take several seconds in a vault with soft-delete enabled. This method therefore returns a poller enabling you to wait for deletion to complete.

begin_delete_secret(name: str, **kwargs: Any) -> LROPoller

Parameters

name: str

Required

Name of the secret to delete.

Returns

A poller for the delete operation. The poller's result method returns the DeletedSecret without waiting for deletion to complete. If the vault has soft-delete enabled and you want to permanently delete the secret with purge_deleted_secret, call the poller's wait method first. It will block until the deletion is complete. The wait method requires secrets/get permission.

Return type

LROPoller[DeletedSecret]

Exceptions

ResourceNotFoundError

if the secret doesn't exist,

HttpResponseError

for other errors

Examples

Delete a secret


   # delete a secret
   deleted_secret_poller = secret_client.begin_delete_secret(secret_name)
   deleted_secret = deleted_secret_poller.result()

   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)

   # if you want to block until secret is deleted server-side, call wait() on the poller
   deleted_secret_poller.wait()

begin_recover_deleted_secret

Recover a deleted secret to its latest version. Possible only in a vault with soft-delete enabled.

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

When this method returns Key Vault has begun recovering the secret. Recovery may take several seconds. This method therefore returns a poller enabling you to wait for recovery to complete. Waiting is only necessary when you want to use the recovered secret in another operation immediately.

Requires the secrets/recover permission.

begin_recover_deleted_secret(name: str, **kwargs: Any) -> LROPoller

Parameters

name: str

Required

Name of the deleted secret to recover

Returns

A poller for the recovery operation. The poller's result method returns the recovered <xref:azure.keyvault.secrets.Secret> without waiting for recovery to complete. If you want to use the recovered secret immediately, call the poller's wait method, which blocks until the secret is ready to use. The wait method requires secrets/get permission.

Return type

LROPoller[SecretProperties]

Exceptions

HttpResponseError

Examples

Recover a deleted secret


   # recover deleted secret to the latest version
   recover_secret_poller = secret_client.begin_recover_deleted_secret(secret_name)
   recovered_secret = recover_secret_poller.result()
   print(recovered_secret.id)
   print(recovered_secret.name)

   # if you want to block until secret is recovered server-side, call wait() on the poller
   recover_secret_poller.wait()

get_deleted_secret

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

get_deleted_secret(name: str, **kwargs: Any) -> DeletedSecret

Parameters

name: str

Required

Name of the deleted secret

Return type

DeletedSecret

Exceptions

ResourceNotFoundError

if the deleted secret doesn't exist,

HttpResponseError

for other errors

Examples

Get a deleted secret


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

get_secret

Get a secret. Requires the secrets/get permission.

get_secret(name: str, version: str = None, **kwargs: Any) -> KeyVaultSecret

Parameters

name: str

Required

The name of the secret

version: str

Required

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

Return type

KeyVaultSecret

Exceptions

ResourceNotFoundError

if the secret doesn't exist,

HttpResponseError

for other errors

Examples

Get a secret


   # get the latest version of a secret
   secret = secret_client.get_secret(secret_name)

   # alternatively, specify a version
   secret = secret_client.get_secret(secret_name, secret.properties.version)

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

list_deleted_secrets

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

Requires secrets/list permission.

list_deleted_secrets(**kwargs: Any) -> ItemPaged[DeletedSecret]

Returns

An iterator of deleted secrets, excluding their values

Return type

ItemPaged[DeletedSecret]

Exceptions

ResourceNotFoundError

if the secret doesn't exist,

HttpResponseError

for other errors

Examples

List deleted secrets


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

   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

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.

list_properties_of_secret_versions(name: str, **kwargs: Any) -> ItemPaged[SecretProperties]

Parameters

name: str

Required

Name of the secret

Returns

An iterator of secrets, excluding their values

Return type

ItemPaged[SecretProperties]

Exceptions

ResourceNotFoundError

if the secret doesn't exist,

HttpResponseError

for other errors

Examples

List all versions of a secret


   secret_versions = secret_client.list_properties_of_secret_versions("secret-name")

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

list_properties_of_secrets

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.

list_properties_of_secrets(**kwargs: Any) -> ItemPaged[SecretProperties]

Returns

An iterator of secrets, excluding their values

Return type

ItemPaged[SecretProperties]

Exceptions

ResourceNotFoundError

if the secret doesn't exist,

HttpResponseError

for other errors

Examples

List all secrets


   # list secrets
   secrets = secret_client.list_properties_of_secrets()

   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

Permanently deletes 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.

purge_deleted_secret(name: str, **kwargs: Any) -> None

Parameters

name: str

Required

Name of the secret to purge

Returns

None

Exceptions

HttpResponseError

Examples


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

restore_secret_backup

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

restore_secret_backup(backup: bytes, **kwargs: Any) -> SecretProperties

Parameters

backup: bytes

Required

A secret backup as returned by backup_secret

Returns

The restored secret

Return type

SecretProperties

Exceptions

ResourceExistsError

if the secret's name is already in use,

HttpResponseError

for other errors

Examples

Restore a backed up secret


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

set_secret

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.

set_secret(name: str, value: str, **kwargs: Any) -> KeyVaultSecret

Parameters

name: str

Required

The name of the secret

value: str

Required

The value of the secret

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

Exceptions

HttpResponseError

Examples

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 = secret_client.set_secret(secret_name, "secret-value", expires_on=expires_on)

   print(secret.name)
   print(secret.properties.version)
   print(secret.properties.expires_on)

update_secret_properties

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.

update_secret_properties(name: str, version: Optional[str] = None, **kwargs: Any) -> SecretProperties

Parameters

name: str

Required

Name of the secret

version: str

Required

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

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

Exceptions

ResourceNotFoundError

if the secret doesn't exist,

HttpResponseError

for other errors

Examples

Update a secret's attributes


   # update attributes of an existing secret

   content_type = "text/plain"
   tags = {"foo": "updated tag"}
   updated_secret_properties = 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)

SecretClient Class

Constructor

Parameters

Examples

Methods

backup_secret

Parameters

Return type

Exceptions

Examples

begin_delete_secret

Parameters

Returns

Return type

Exceptions

Examples

begin_recover_deleted_secret

Parameters

Returns

Return type

Exceptions

Examples

get_deleted_secret

Parameters

Return type

Exceptions

Examples

get_secret

Parameters

Return type

Exceptions

Examples

list_deleted_secrets

Returns

Return type

Exceptions

Examples

list_properties_of_secret_versions

Parameters

Returns

Return type

Exceptions

Examples

list_properties_of_secrets

Returns

Return type

Exceptions

Examples

purge_deleted_secret

Parameters

Returns

Exceptions

Examples

restore_secret_backup

Parameters

Returns

Return type

Exceptions

Examples

set_secret

Parameters

Return type

Exceptions

Examples

update_secret_properties

Parameters

Return type

Exceptions

Examples

Feedback