Share via

KeyClient Class

  • Reference

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

Inheritance
azure.keyvault.keys._shared.client_base.KeyVaultClientBase
KeyClient

Constructor

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

Parameters

Name Description
vault_url
Required
str

URL of the vault the client will access. This is also called the vault's "DNS Name". You should validate that this URL references a valid Key Vault or Managed HSM resource. See https://aka.ms/azsdk/blog/vault-uri for details.
credential
Required
TokenCredential

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

Keyword-Only Parameters

Name Description
api_version
ApiVersion or str

Version of the service API to use. Defaults to the most recent.
verify_challenge_resource
bool

Whether to verify the authentication challenge resource matches the Key Vault or Managed HSM domain. Defaults to True.

Methods

backup_key

Back up a key in a protected form useable only by Azure Key Vault.

Requires keys/backup permission.

This is intended to allow copying a key from one vault to another. Both vaults must be owned by the same Azure subscription. Also, backup / restore cannot be performed across geopolitical boundaries. For example, a backup from a vault in a USA region cannot be restored to a vault in an EU region.
begin_delete_key

Delete all versions of a key and its cryptographic material.

Requires keys/delete permission. When this method returns Key Vault has begun deleting the key. 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_key

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

Requires keys/recover permission.

When this method returns Key Vault has begun recovering the key. 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 key in another operation immediately.
close

Close sockets opened by the client.

Calling this method is unnecessary when using the client as a context manager.
create_ec_key

Create a new elliptic curve key or, if name is already in use, create a new version of the key.

Requires the keys/create permission.
create_key

Create a key or, if name is already in use, create a new version of the key.

Requires keys/create permission.
create_oct_key

Create a new octet sequence (symmetric) key or, if name is in use, create a new version of the key.

Requires the keys/create permission.
create_rsa_key

Create a new RSA key or, if name is already in use, create a new version of the key

Requires the keys/create permission.
get_cryptography_client

Gets a CryptographyClient for the given key.
get_deleted_key

Get a deleted key. Possible only in a vault with soft-delete enabled.

Requires keys/get permission.
get_key

Get a key's attributes and, if it's an asymmetric key, its public material.

Requires keys/get permission.
get_key_rotation_policy

Get the rotation policy of a Key Vault key.
get_random_bytes

Get the requested number of random bytes from a managed HSM.
import_key

Import a key created externally.

Requires keys/import permission. If name is already in use, the key will be imported as a new version.
list_deleted_keys

List all deleted keys, including the public part of each. Possible only in a vault with soft-delete enabled.

Requires keys/list permission.
list_properties_of_key_versions

List the identifiers and properties of a key's versions.

Requires keys/list permission.
list_properties_of_keys

List identifiers and properties of all keys in the vault.

Requires keys/list permission.
purge_deleted_key

Permanently deletes a deleted key. Only possible in a vault with soft-delete enabled.

Performs an irreversible deletion of the specified key, 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 key before its scheduled_purge_date.

Requires keys/purge permission.
release_key

Releases a key.

The release key operation is applicable to all key types. The target key must be marked exportable. This operation requires the keys/release permission.
restore_key_backup

Restore a key backup to the vault.

Requires keys/restore permission.

This imports all versions of the key, with its name, attributes, and access control policies. If the key's name is already in use, restoring it will fail. Also, the target vault must be owned by the same Microsoft Azure subscription as the source vault.
rotate_key

Rotate the key based on the key policy by generating a new version of the key.

This operation requires the keys/rotate permission.
send_request

Runs a network request using the client's existing pipeline.

The request URL can be relative to the vault URL. The service API version used for the request is the same as the client's unless otherwise specified. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.
update_key_properties

Change a key's properties (not its cryptographic material).

Requires keys/update permission.
update_key_rotation_policy

Updates the rotation policy of a Key Vault key.

This operation requires the keys/update permission.

backup_key

Back up a key in a protected form useable only by Azure Key Vault.

Requires keys/backup permission.

This is intended to allow copying a key from one vault to another. Both vaults must be owned by the same Azure subscription. Also, backup / restore cannot be performed across geopolitical boundaries. For example, a backup from a vault in a USA region cannot be restored to a vault in an EU region.

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

Parameters

Name Description
name
Required
str

The name of the key to back up

Returns

Type Description
bytes

The key backup result, in a protected bytes format that can only be used by Azure Key Vault.

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

begin_delete_key

Delete all versions of a key and its cryptographic material.

Requires keys/delete permission. When this method returns Key Vault has begun deleting the key. 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_key(name: str, **kwargs: Any) -> LROPoller[DeletedKey]

Parameters

Name Description
name
Required
str

The name of the key to delete.

Returns

Type Description
LROPoller[DeletedKey]

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

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

begin_recover_deleted_key

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

Requires keys/recover permission.

When this method returns Key Vault has begun recovering the key. 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 key in another operation immediately.

begin_recover_deleted_key(name: str, **kwargs: Any) -> LROPoller[KeyVaultKey]

Parameters

Name Description
name
Required
str

The name of the deleted key to recover

Returns

Type Description
LROPoller[KeyVaultKey]

A poller for the recovery operation. The poller's result method returns the recovered KeyVaultKey without waiting for recovery to complete. If you want to use the recovered key immediately, call the poller's wait method, which blocks until the key is ready to use. The wait method requires keys/get permission.

Exceptions

Type Description
HttpResponseError

close

Close sockets opened by the client.

Calling this method is unnecessary when using the client as a context manager.

close() -> None

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

create_ec_key

Create a new elliptic curve key or, if name is already in use, create a new version of the key.

Requires the keys/create permission.

create_ec_key(name: str, *, curve: str | KeyCurveName | None = None, key_operations: List[str | KeyOperation] | None = None, hardware_protected: bool | None = False, enabled: bool | None = None, tags: Dict[str, str] | None = None, not_before: datetime | None = None, expires_on: datetime | None = None, exportable: bool | None = None, release_policy: KeyReleasePolicy | None = None, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
name
Required
str

The name for the new key.

Keyword-Only Parameters

Name Description
curve
KeyCurveName or str or None

Elliptic curve name. Defaults to the NIST P-256 elliptic curve.
key_operations
List[KeyOperation or str] or None

Allowed key operations
hardware_protected
bool or None

Whether the key should be created in a hardware security module. Defaults to False.
enabled
bool or None

Whether the key is enabled for use.
tags
dict[str, str] or None

Application specific metadata in the form of key-value pairs.
not_before
datetime or None

Not before date of the key in UTC
expires_on
datetime or None

Expiry date of the key in UTC
exportable
bool or None

Whether the private key can be exported.
release_policy
KeyReleasePolicy or None

The policy rules under which the key can be exported.

Returns

Type Description
KeyVaultKey

The created key

Exceptions

Type Description
HttpResponseError

create_key

Create a key or, if name is already in use, create a new version of the key.

Requires keys/create permission.

create_key(name: str, key_type: str | KeyType, *, size: int | None = None, curve: str | KeyCurveName | None = None, public_exponent: int | None = None, key_operations: List[str | KeyOperation] | None = None, enabled: bool | None = None, tags: Dict[str, str] | None = None, not_before: datetime | None = None, expires_on: datetime | None = None, exportable: bool | None = None, release_policy: KeyReleasePolicy | None = None, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
name
Required
str

The name of the new key.
key_type
Required
KeyType or str

The type of key to create

Keyword-Only Parameters

Name Description
size
int or None

Key size in bits. Applies only to RSA and symmetric keys. Consider using create_rsa_key or create_oct_key instead.
curve
KeyCurveName or str or None

Elliptic curve name. Applies only to elliptic curve keys. Defaults to the NIST P-256 elliptic curve. To create an elliptic curve key, consider using create_ec_key instead.
public_exponent
int or None

The RSA public exponent to use. Applies only to RSA keys created in a Managed HSM.
key_operations
List[KeyOperation or str] or None

Allowed key operations
enabled
bool or None

Whether the key is enabled for use.
tags
dict[str, str] or None

Application specific metadata in the form of key-value pairs.
not_before
datetime or None

Not before date of the key in UTC
expires_on
datetime or None

Expiry date of the key in UTC
exportable
bool or None

Whether the private key can be exported.
release_policy
KeyReleasePolicy or None

The policy rules under which the key can be exported.

Returns

Type Description
KeyVaultKey

The created key

Exceptions

Type Description
HttpResponseError

create_oct_key

Create a new octet sequence (symmetric) key or, if name is in use, create a new version of the key.

Requires the keys/create permission.

create_oct_key(name: str, *, size: int | None = None, key_operations: List[str | KeyOperation] | None = None, hardware_protected: bool | None = False, enabled: bool | None = None, tags: Dict[str, str] | None = None, not_before: datetime | None = None, expires_on: datetime | None = None, exportable: bool | None = None, release_policy: KeyReleasePolicy | None = None, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
name
Required
str

The name for the new key.

Keyword-Only Parameters

Name Description
size
int or None

Key size in bits, for example 128, 192, or 256.
key_operations
List[KeyOperation or str] or None

Allowed key operations.
hardware_protected
bool or None

Whether the key should be created in a hardware security module. Defaults to False.
enabled
bool or None

Whether the key is enabled for use.
tags
dict[str, str] or None

Application specific metadata in the form of key-value pairs.
not_before
datetime or None

Not before date of the key in UTC
expires_on
datetime or None

Expiry date of the key in UTC
exportable
bool or None

Whether the key can be exported.
release_policy
KeyReleasePolicy or None

The policy rules under which the key can be exported.

Returns

Type Description
KeyVaultKey

The created key

Exceptions

Type Description
HttpResponseError

create_rsa_key

Create a new RSA key or, if name is already in use, create a new version of the key

Requires the keys/create permission.

create_rsa_key(name: str, *, size: int | None = None, public_exponent: int | None = None, hardware_protected: bool | None = False, key_operations: List[str | KeyOperation] | None = None, enabled: bool | None = None, tags: Dict[str, str] | None = None, not_before: datetime | None = None, expires_on: datetime | None = None, exportable: bool | None = None, release_policy: KeyReleasePolicy | None = None, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
name
Required
str

The name for the new key.

Keyword-Only Parameters

Name Description
size
int or None

Key size in bits, for example 2048, 3072, or 4096.
public_exponent
int or None

The RSA public exponent to use. Applies only to RSA keys created in a Managed HSM.
hardware_protected
bool or None

Whether the key should be created in a hardware security module. Defaults to False.
key_operations
List[KeyOperation or str] or None

Allowed key operations
enabled
bool or None

Whether the key is enabled for use.
tags
dict[str, str] or None

Application specific metadata in the form of key-value pairs.
not_before
datetime or None

Not before date of the key in UTC
expires_on
datetime or None

Expiry date of the key in UTC
exportable
bool or None

Whether the private key can be exported.
release_policy
KeyReleasePolicy or None

The policy rules under which the key can be exported.

Returns

Type Description
KeyVaultKey

The created key

Exceptions

Type Description
HttpResponseError

get_cryptography_client

Gets a CryptographyClient for the given key.

get_cryptography_client(key_name: str, *, key_version: str | None = None, **kwargs) -> CryptographyClient

Parameters

Name Description
key_name
Required
str

The name of the key used to perform cryptographic operations.

Keyword-Only Parameters

Name Description
key_version
str or None

Optional version of the key used to perform cryptographic operations.

Returns

Type Description
CryptographyClient

A CryptographyClient using the same options, credentials, and HTTP client as this KeyClient.

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

get_deleted_key

Get a deleted key. Possible only in a vault with soft-delete enabled.

Requires keys/get permission.

get_deleted_key(name: str, **kwargs: Any) -> DeletedKey

Parameters

Name Description
name
Required
str

The name of the key

Returns

Type Description
DeletedKey

The deleted key

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

get_key

Get a key's attributes and, if it's an asymmetric key, its public material.

Requires keys/get permission.

get_key(name: str, version: str | None = None, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
name
Required
str

The name of the key to get.
version
Required
str or None

(optional) A specific version of the key to get. If not specified, gets the latest version of the key.

Returns

Type Description
KeyVaultKey

The fetched key.

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

get_key_rotation_policy

Get the rotation policy of a Key Vault key.

get_key_rotation_policy(key_name: str, **kwargs: Any) -> KeyRotationPolicy

Parameters

Name Description
key_name
Required
str

The name of the key.

Returns

Type Description
KeyRotationPolicy

The key rotation policy.

Exceptions

Type Description
HttpResponseError

get_random_bytes

Get the requested number of random bytes from a managed HSM.

get_random_bytes(count: int, **kwargs: Any) -> bytes

Parameters

Name Description
count
Required
int

The requested number of random bytes.

Returns

Type Description
bytes

The random bytes.

Exceptions

Type Description
ValueError
HttpResponseError

the former if less than one random byte is requested; the latter for other errors

import_key

Import a key created externally.

Requires keys/import permission. If name is already in use, the key will be imported as a new version.

import_key(name: str, key: JsonWebKey, *, hardware_protected: bool | None = None, enabled: bool | None = None, tags: Dict[str, str] | None = None, not_before: datetime | None = None, expires_on: datetime | None = None, exportable: bool | None = None, release_policy: KeyReleasePolicy | None = None, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
name
Required
str

Name for the imported key
key
Required
JsonWebKey

The JSON web key to import

Keyword-Only Parameters

Name Description
hardware_protected
bool or None

Whether the key should be backed by a hardware security module
enabled
bool or None

Whether the key is enabled for use.
tags
dict[str, str] or None

Application specific metadata in the form of key-value pairs.
not_before
datetime or None

Not before date of the key in UTC
expires_on
datetime or None

Expiry date of the key in UTC
exportable
bool or None

Whether the private key can be exported.
release_policy
KeyReleasePolicy or None

The policy rules under which the key can be exported.

Returns

Type Description
KeyVaultKey

The imported key

Exceptions

Type Description
HttpResponseError

list_deleted_keys

List all deleted keys, including the public part of each. Possible only in a vault with soft-delete enabled.

Requires keys/list permission.

list_deleted_keys(**kwargs: Any) -> ItemPaged[DeletedKey]

Returns

Type Description
ItemPaged[DeletedKey]

An iterator of deleted keys

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

list_properties_of_key_versions

List the identifiers and properties of a key's versions.

Requires keys/list permission.

list_properties_of_key_versions(name: str, **kwargs: Any) -> ItemPaged[KeyProperties]

Parameters

Name Description
name
Required
str

The name of the key

Returns

Type Description
ItemPaged[KeyProperties]

An iterator of keys without their cryptographic material

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

list_properties_of_keys

List identifiers and properties of all keys in the vault.

Requires keys/list permission.

list_properties_of_keys(**kwargs: Any) -> ItemPaged[KeyProperties]

Returns

Type Description
ItemPaged[KeyProperties]

An iterator of keys without their cryptographic material or version information

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

purge_deleted_key

Permanently deletes a deleted key. Only possible in a vault with soft-delete enabled.

Performs an irreversible deletion of the specified key, 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 key before its scheduled_purge_date.

Requires keys/purge permission.

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

Parameters

Name Description
name
Required
str

The name of the deleted key to purge

Returns

Type Description

None

Exceptions

Type Description
HttpResponseError

Examples


   # if the vault has soft-delete enabled, purge permanently deletes a deleted key
   # (with soft-delete disabled, begin_delete_key is permanent)
   key_client.purge_deleted_key("key-name")

release_key

Releases a key.

The release key operation is applicable to all key types. The target key must be marked exportable. This operation requires the keys/release permission.

release_key(name: str, target_attestation_token: str, *, version: str | None = None, algorithm: str | KeyExportEncryptionAlgorithm | None = None, nonce: str | None = None, **kwargs: Any) -> ReleaseKeyResult

Parameters

Name Description
name
Required
str

The name of the key to get.
target_attestation_token
Required
str

The attestation assertion for the target of the key release.

Keyword-Only Parameters

Name Description
version
str or None

A specific version of the key to release. If unspecified, the latest version is released.
algorithm
str or KeyExportEncryptionAlgorithm or None

The encryption algorithm to use to protect the released key material.
nonce
str or None

A client-provided nonce for freshness.

Returns

Type Description
ReleaseKeyResult

The result of the key release.

Exceptions

Type Description
HttpResponseError

restore_key_backup

Restore a key backup to the vault.

Requires keys/restore permission.

This imports all versions of the key, with its name, attributes, and access control policies. If the key's name is already in use, restoring it will fail. Also, the target vault must be owned by the same Microsoft Azure subscription as the source vault.

restore_key_backup(backup: bytes, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
backup
Required
bytes

A key backup as returned by backup_key

Returns

Type Description
KeyVaultKey

The restored key

Exceptions

Type Description
ResourceExistsError
HttpResponseError

the former if the backed up key's name is already in use; the latter for other errors

rotate_key

Rotate the key based on the key policy by generating a new version of the key.

This operation requires the keys/rotate permission.

rotate_key(name: str, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
name
Required
str

The name of the key to rotate.

Returns

Type Description
KeyVaultKey

The new version of the rotated key.

Exceptions

Type Description
HttpResponseError

send_request

Runs a network request using the client's existing pipeline.

The request URL can be relative to the vault URL. The service API version used for the request is the same as the client's unless otherwise specified. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.

send_request(request: HttpRequest, *, stream: bool = False, **kwargs: Any) -> HttpResponse

Parameters

Name Description
request
Required
HttpRequest

The network request you want to make.

Keyword-Only Parameters

Name Description
stream
bool

Whether the response payload will be streamed. Defaults to False.

Returns

Type Description
HttpResponse

The response of your network call. Does not do error handling on your response.

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

update_key_properties

Change a key's properties (not its cryptographic material).

Requires keys/update permission.

update_key_properties(name: str, version: str | None = None, *, key_operations: List[str | KeyOperation] | None = None, enabled: bool | None = None, tags: Dict[str, str] | None = None, not_before: datetime | None = None, expires_on: datetime | None = None, release_policy: KeyReleasePolicy | None = None, **kwargs: Any) -> KeyVaultKey

Parameters

Name Description
name
Required
str

The name of key to update
version
Required
str or None

(optional) The version of the key to update. If unspecified, the latest version is updated.

Keyword-Only Parameters

Name Description
key_operations
List[KeyOperation or str] or None

Allowed key operations
enabled
bool or None

Whether the key is enabled for use.
tags
dict[str, str] or None

Application specific metadata in the form of key-value pairs.
not_before
datetime or None

Not before date of the key in UTC
expires_on
datetime or None

Expiry date of the key in UTC
release_policy
KeyReleasePolicy or None

The policy rules under which the key can be exported.

Returns

Type Description
KeyVaultKey

The updated key

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the key doesn't exist; the latter for other errors

update_key_rotation_policy

Updates the rotation policy of a Key Vault key.

This operation requires the keys/update permission.

update_key_rotation_policy(key_name: str, policy: KeyRotationPolicy, *, lifetime_actions: List[KeyRotationLifetimeAction] | None = None, expires_in: str | None = None, **kwargs: Any) -> KeyRotationPolicy

Parameters

Name Description
key_name
Required
str

The name of the key in the given vault.
policy
Required
KeyRotationPolicy

The new rotation policy for the key.

Keyword-Only Parameters

Name Description
lifetime_actions
List[KeyRotationLifetimeAction]

Actions that will be performed by Key Vault over the lifetime of a key. This will override the lifetime actions of the provided policy.
expires_in
str

The expiry time of the policy that will be applied on new key versions, defined as an ISO 8601 duration. For example: 90 days is "P90D", 3 months is "P3M", and 48 hours is "PT48H". See Wikipedia for more information on ISO 8601 durations. This will override the expiry time of the provided policy.

Returns

Type Description
KeyRotationPolicy

The updated rotation policy.

Exceptions

Type Description
HttpResponseError

Attributes

vault_url