KeyClient class
The KeyClient provides methods to manage KeyVaultKey in the Azure Key Vault. The client supports creating, retrieving, updating, deleting, purging, backing up, restoring and listing KeyVaultKeys. The client also supports listing DeletedKey for a soft-delete enabled Azure Key Vault.
Constructors
| Key |
Creates an instance of KeyClient. Example usage: |
Properties
| vault |
The base URL to the vault |
Methods
| backup |
Requests that a backup of the specified key be downloaded to the client. All versions of the key will be downloaded. This operation requires the keys/backup permission. Example usage: Backs up the specified key. |
| begin |
The delete operation applies to any key stored in Azure Key Vault. Individual versions of a key can not be deleted, only all versions of a given key at once. This function returns a Long Running Operation poller that allows you to wait indefinitely until the key is deleted. This operation requires the keys/delete permission. Example usage: Deletes a key from a specified key vault. |
| begin |
Recovers the deleted key in the specified vault. This operation can only be performed on a soft-delete enabled vault. This function returns a Long Running Operation poller that allows you to wait indefinitely until the deleted key is recovered. This operation requires the keys/recover permission. Example usage: Recovers the deleted key to the latest version. |
| create |
The createEcKey method creates a new elliptic curve key in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission. Example usage: Creates a new key, stores it, then returns key parameters and properties to the client. |
| create |
The create key operation can be used to create any key type in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission. Example usage: Creates a new key, stores it, then returns key parameters and properties to the client. |
| create |
The createOctKey method creates a new OCT key in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission. Example usage: Creates a new key, stores it, then returns key parameters and properties to the client. |
| create |
The createRSAKey method creates a new RSA key in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission. Example usage: Creates a new key, stores it, then returns key parameters and properties to the client. |
| get |
Gets a CryptographyClient for the given key. Example usage: |
| get |
The getDeletedKey method returns the specified deleted key along with its properties. This operation requires the keys/get permission. Example usage: Gets the specified deleted key. |
| get |
The getKey method gets a specified key and is applicable to any key stored in Azure Key Vault. This operation requires the keys/get permission. Example usage: Get a specified key from a given key vault. |
| get |
Gets the rotation policy of a Key Vault Key. By default, all keys have a policy that will notify 30 days before expiry. This operation requires the keys/get permission. Example usage: |
| get |
Gets the requested number of bytes containing random values from a managed HSM. This operation requires the managedHsm/rng permission. Example usage: |
| import |
The import key operation may be used to import any key type into an Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. This operation requires the keys/import permission. Example usage: Imports an externally created key, stores it, and returns key parameters and properties to the client. |
| list |
Iterates the deleted keys in the vault. The full key identifier and properties are provided in the response. No values are returned for the keys. This operations requires the keys/list permission. Example usage: List all keys in the vault |
| list |
Iterates the latest version of all keys in the vault. The full key identifier and properties are provided in the response. No values are returned for the keys. This operations requires the keys/list permission. Example usage: List all keys in the vault |
| list |
Iterates all versions of the given key in the vault. The full key identifier, properties, and tags are provided in the response. This operation requires the keys/list permission. Example usage: |
| purge |
The purge deleted key operation removes the key permanently, without the possibility of recovery. This operation can only be enabled on a soft-delete enabled vault. This operation requires the keys/purge permission. Example usage: Permanently deletes the specified key. |
| release |
Releases a key from a managed HSM. The release key operation is applicable to all key types. The operation requires the key to be marked exportable and the keys/release permission. Example usage: |
| restore |
Restores a backed up key, and all its versions, to a vault. This operation requires the keys/restore permission. Example usage: Restores a backed up key to a vault. |
| rotate |
Rotates the key based on the key policy by generating a new version of the key. This operation requires the keys/rotate permission. Example usage: |
| update |
The updateKeyProperties method changes specified properties of an existing stored key. Properties that are not specified in the request are left unchanged. The value of a key itself cannot be changed. This operation requires the keys/set permission. Example usage: Updates the properties associated with a specified key in a given key vault. |
| update |
The updateKeyProperties method changes specified properties of the latest version of an existing stored key. Properties that are not specified in the request are left unchanged. The value of a key itself cannot be changed. This operation requires the keys/set permission. Example usage: Updates the properties associated with a specified key in a given key vault. |
| update |
Updates the rotation policy of a Key Vault Key. This operation requires the keys/update permission. Example usage: |
Constructor Details
KeyClient(string, TokenCredential, KeyClientOptions)
Creates an instance of KeyClient.
Example usage:
import { KeyClient } from "@azure/keyvault-keys";
import { DefaultAzureCredential } from "@azure/identity";
let vaultUrl = `https://<MY KEYVAULT HERE>.vault.azure.net`;
let credentials = new DefaultAzureCredential();
let client = new KeyClient(vaultUrl, credentials);
new KeyClient(vaultUrl: string, credential: TokenCredential, pipelineOptions?: KeyClientOptions)Parameters
- vaultUrl
-
string
the URL of the Key Vault. It should have this shape: https://${your-key-vault-name}.vault.azure.net. 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
- TokenCredential
An object that implements the TokenCredential interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs.
- pipelineOptions
- KeyClientOptions
Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration.
Property Details
vaultUrl
The base URL to the vault
vaultUrl: stringProperty Value
string
Method Details
backupKey(string, BackupKeyOptions)
Requests that a backup of the specified key be downloaded to the client. All versions of the key will be downloaded. This operation requires the keys/backup permission.
Example usage:
let client = new KeyClient(url, credentials);
let backupContents = await client.backupKey("MyKey");
Backs up the specified key.
function backupKey(name: string, options?: BackupKeyOptions): Promise<undefined | Uint8Array>Parameters
- name
-
string
The name of the key.
- options
- BackupKeyOptions
The optional parameters.
Returns
Promise<undefined | Uint8Array>
beginDeleteKey(string, BeginDeleteKeyOptions)
The delete operation applies to any key stored in Azure Key Vault. Individual versions of a key can not be deleted, only all versions of a given key at once.
This function returns a Long Running Operation poller that allows you to wait indefinitely until the key is deleted.
This operation requires the keys/delete permission.
Example usage:
const client = new KeyClient(url, credentials);
await client.createKey("MyKey", "EC");
const poller = await client.beginDeleteKey("MyKey");
// Serializing the poller
const serialized = poller.toString();
// A new poller can be created with:
// await client.beginDeleteKey("MyKey", { resumeFrom: serialized });
// Waiting until it's done
const deletedKey = await poller.pollUntilDone();
console.log(deletedKey);
Deletes a key from a specified key vault.
function beginDeleteKey(name: string, options?: BeginDeleteKeyOptions): Promise<PollerLike<PollOperationState<DeletedKey>, DeletedKey>>Parameters
- name
-
string
The name of the key.
- options
- BeginDeleteKeyOptions
The optional parameters.
Returns
Promise<PollerLike<PollOperationState<DeletedKey>, DeletedKey>>
beginRecoverDeletedKey(string, BeginRecoverDeletedKeyOptions)
Recovers the deleted key in the specified vault. This operation can only be performed on a soft-delete enabled vault.
This function returns a Long Running Operation poller that allows you to wait indefinitely until the deleted key is recovered.
This operation requires the keys/recover permission.
Example usage:
const client = new KeyClient(url, credentials);
await client.createKey("MyKey", "EC");
const deletePoller = await client.beginDeleteKey("MyKey");
await deletePoller.pollUntilDone();
const poller = await client.beginRecoverDeletedKey("MyKey");
// Serializing the poller
const serialized = poller.toString();
// A new poller can be created with:
// await client.beginRecoverDeletedKey("MyKey", { resumeFrom: serialized });
// Waiting until it's done
const key = await poller.pollUntilDone();
console.log(key);
Recovers the deleted key to the latest version.
function beginRecoverDeletedKey(name: string, options?: BeginRecoverDeletedKeyOptions): Promise<PollerLike<PollOperationState<DeletedKey>, DeletedKey>>Parameters
- name
-
string
The name of the deleted key.
- options
- BeginRecoverDeletedKeyOptions
The optional parameters.
Returns
Promise<PollerLike<PollOperationState<DeletedKey>, DeletedKey>>
createEcKey(string, CreateEcKeyOptions)
The createEcKey method creates a new elliptic curve key in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission.
Example usage:
let client = new KeyClient(url, credentials);
let result = await client.createEcKey("MyKey", { curve: "P-256" });
Creates a new key, stores it, then returns key parameters and properties to the client.
function createEcKey(name: string, options?: CreateEcKeyOptions): Promise<KeyVaultKey>Parameters
- name
-
string
The name of the key.
- options
- CreateEcKeyOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
createKey(string, string, CreateKeyOptions)
The create key operation can be used to create any key type in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission.
Example usage:
let client = new KeyClient(url, credentials);
// Create an elliptic-curve key:
let result = await client.createKey("MyKey", "EC");
Creates a new key, stores it, then returns key parameters and properties to the client.
function createKey(name: string, keyType: string, options?: CreateKeyOptions): Promise<KeyVaultKey>Parameters
- name
-
string
The name of the key.
- keyType
-
string
The type of the key. One of the following: 'EC', 'EC-HSM', 'RSA', 'RSA-HSM', 'oct'.
- options
- CreateKeyOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
createOctKey(string, CreateOctKeyOptions)
The createOctKey method creates a new OCT key in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission.
Example usage:
let client = new KeyClient(url, credentials);
let result = await client.createOctKey("MyKey", { hsm: true });
Creates a new key, stores it, then returns key parameters and properties to the client.
function createOctKey(name: string, options?: CreateOctKeyOptions): Promise<KeyVaultKey>Parameters
- name
-
string
The name of the key.
- options
- CreateOctKeyOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
createRsaKey(string, CreateRsaKeyOptions)
The createRSAKey method creates a new RSA key in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission.
Example usage:
let client = new KeyClient(url, credentials);
let result = await client.createRsaKey("MyKey", { keySize: 2048 });
Creates a new key, stores it, then returns key parameters and properties to the client.
function createRsaKey(name: string, options?: CreateRsaKeyOptions): Promise<KeyVaultKey>Parameters
- name
-
string
The name of the key.
- options
- CreateRsaKeyOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
getCryptographyClient(string, GetCryptographyClientOptions)
Gets a CryptographyClient for the given key.
Example usage:
let client = new KeyClient(url, credentials);
// get a cryptography client for a given key
let cryptographyClient = client.getCryptographyClient("MyKey");
function getCryptographyClient(keyName: string, options?: GetCryptographyClientOptions): CryptographyClientParameters
- keyName
-
string
- options
- GetCryptographyClientOptions
Returns
- A CryptographyClient using the same options, credentials, and http client as this KeyClient
getDeletedKey(string, GetDeletedKeyOptions)
The getDeletedKey method returns the specified deleted key along with its properties. This operation requires the keys/get permission.
Example usage:
let client = new KeyClient(url, credentials);
let key = await client.getDeletedKey("MyDeletedKey");
Gets the specified deleted key.
function getDeletedKey(name: string, options?: GetDeletedKeyOptions): Promise<DeletedKey>Parameters
- name
-
string
The name of the key.
- options
- GetDeletedKeyOptions
The optional parameters.
Returns
Promise<DeletedKey>
getKey(string, GetKeyOptions)
The getKey method gets a specified key and is applicable to any key stored in Azure Key Vault. This operation requires the keys/get permission.
Example usage:
let client = new KeyClient(url, credentials);
let key = await client.getKey("MyKey");
Get a specified key from a given key vault.
function getKey(name: string, options?: GetKeyOptions): Promise<KeyVaultKey>Parameters
- name
-
string
The name of the key.
- options
- GetKeyOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
getKeyRotationPolicy(string, GetKeyRotationPolicyOptions)
Gets the rotation policy of a Key Vault Key. By default, all keys have a policy that will notify 30 days before expiry.
This operation requires the keys/get permission. Example usage:
let client = new KeyClient(vaultUrl, credentials);
let result = await client.getKeyRotationPolicy("myKey");
function getKeyRotationPolicy(keyName: string, options?: GetKeyRotationPolicyOptions): Promise<KeyRotationPolicy>Parameters
- keyName
-
string
The name of the key.
- options
- GetKeyRotationPolicyOptions
The optional parameters.
Returns
Promise<KeyRotationPolicy>
getRandomBytes(number, GetRandomBytesOptions)
Gets the requested number of bytes containing random values from a managed HSM. This operation requires the managedHsm/rng permission.
Example usage:
let client = new KeyClient(vaultUrl, credentials);
let { bytes } = await client.getRandomBytes(10);
function getRandomBytes(count: number, options?: GetRandomBytesOptions): Promise<Uint8Array>Parameters
- count
-
number
The number of bytes to generate between 1 and 128 inclusive.
- options
- GetRandomBytesOptions
The optional parameters.
Returns
Promise<Uint8Array>
importKey(string, JsonWebKey_2, ImportKeyOptions)
The import key operation may be used to import any key type into an Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. This operation requires the keys/import permission.
Example usage:
let client = new KeyClient(url, credentials);
// Key contents in myKeyContents
let result = await client.importKey("MyKey", myKeyContents);
Imports an externally created key, stores it, and returns key parameters and properties to the client.
function importKey(name: string, key: JsonWebKey_2, options?: ImportKeyOptions): Promise<KeyVaultKey>Parameters
- name
-
string
Name for the imported key.
- key
- JsonWebKey
The JSON web key.
- options
- ImportKeyOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
listDeletedKeys(ListDeletedKeysOptions)
Iterates the deleted keys in the vault. The full key identifier and properties are provided in the response. No values are returned for the keys. This operations requires the keys/list permission.
Example usage:
let client = new KeyClient(url, credentials);
for await (const deletedKey of client.listDeletedKeys()) {
console.log("deleted key: ", deletedKey);
}
List all keys in the vault
function listDeletedKeys(options?: ListDeletedKeysOptions): PagedAsyncIterableIterator<DeletedKey, DeletedKey[], PageSettings>Parameters
- options
- ListDeletedKeysOptions
The optional parameters.
Returns
listPropertiesOfKeys(ListPropertiesOfKeysOptions)
Iterates the latest version of all keys in the vault. The full key identifier and properties are provided in the response. No values are returned for the keys. This operations requires the keys/list permission.
Example usage:
let client = new KeyClient(url, credentials);
for await (const keyProperties of client.listPropertiesOfKeys()) {
const key = await client.getKey(keyProperties.name);
console.log("key: ", key);
}
List all keys in the vault
function listPropertiesOfKeys(options?: ListPropertiesOfKeysOptions): PagedAsyncIterableIterator<KeyProperties, KeyProperties[], PageSettings>Parameters
- options
- ListPropertiesOfKeysOptions
The optional parameters.
Returns
listPropertiesOfKeyVersions(string, ListPropertiesOfKeyVersionsOptions)
Iterates all versions of the given key in the vault. The full key identifier, properties, and tags are provided in the response. This operation requires the keys/list permission.
Example usage:
let client = new KeyClient(url, credentials);
for await (const keyProperties of client.listPropertiesOfKeyVersions("MyKey")) {
const key = await client.getKey(keyProperties.name);
console.log("key version: ", key);
}
function listPropertiesOfKeyVersions(name: string, options?: ListPropertiesOfKeyVersionsOptions): PagedAsyncIterableIterator<KeyProperties, KeyProperties[], PageSettings>Parameters
- name
-
string
Name of the key to fetch versions for
The optional parameters.
Returns
purgeDeletedKey(string, PurgeDeletedKeyOptions)
The purge deleted key operation removes the key permanently, without the possibility of recovery. This operation can only be enabled on a soft-delete enabled vault. This operation requires the keys/purge permission.
Example usage:
const client = new KeyClient(url, credentials);
const deletePoller = await client.beginDeleteKey("MyKey")
await deletePoller.pollUntilDone();
await client.purgeDeletedKey("MyKey");
Permanently deletes the specified key.
function purgeDeletedKey(name: string, options?: PurgeDeletedKeyOptions): Promise<void>Parameters
- name
-
string
The name of the key.
- options
- PurgeDeletedKeyOptions
The optional parameters.
Returns
Promise<void>
releaseKey(string, string, ReleaseKeyOptions)
Releases a key from a managed HSM.
The release key operation is applicable to all key types. The operation requires the key to be marked exportable and the keys/release permission.
Example usage:
let client = new KeyClient(vaultUrl, credentials);
let result = await client.releaseKey("myKey", target)
function releaseKey(name: string, targetAttestationToken: string, options?: ReleaseKeyOptions): Promise<ReleaseKeyResult>Parameters
- name
-
string
The name of the key.
- targetAttestationToken
-
string
The attestation assertion for the target of the key release.
- options
- ReleaseKeyOptions
The optional parameters.
Returns
Promise<ReleaseKeyResult>
restoreKeyBackup(Uint8Array, RestoreKeyBackupOptions)
Restores a backed up key, and all its versions, to a vault. This operation requires the keys/restore permission.
Example usage:
let client = new KeyClient(url, credentials);
let backupContents = await client.backupKey("MyKey");
// ...
let key = await client.restoreKeyBackup(backupContents);
Restores a backed up key to a vault.
function restoreKeyBackup(backup: Uint8Array, options?: RestoreKeyBackupOptions): Promise<KeyVaultKey>Parameters
- backup
-
Uint8Array
The backup blob associated with a key bundle.
- options
- RestoreKeyBackupOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
rotateKey(string, RotateKeyOptions)
Rotates the key based on the key policy by generating a new version of the key. This operation requires the keys/rotate permission.
Example usage:
let client = new KeyClient(vaultUrl, credentials);
let key = await client.rotateKey("MyKey");
function rotateKey(name: string, options?: RotateKeyOptions): Promise<KeyVaultKey>Parameters
- name
-
string
The name of the key to rotate.
- options
- RotateKeyOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
updateKeyProperties(string, string, UpdateKeyPropertiesOptions)
The updateKeyProperties method changes specified properties of an existing stored key. Properties that are not specified in the request are left unchanged. The value of a key itself cannot be changed. This operation requires the keys/set permission.
Example usage:
let keyName = "MyKey";
let client = new KeyClient(vaultUrl, credentials);
let key = await client.getKey(keyName);
let result = await client.updateKeyProperties(keyName, key.properties.version, { enabled: false });
Updates the properties associated with a specified key in a given key vault.
function updateKeyProperties(name: string, keyVersion: string, options?: UpdateKeyPropertiesOptions): Promise<KeyVaultKey>Parameters
- name
-
string
The name of the key.
- keyVersion
-
string
The version of the key.
- options
- UpdateKeyPropertiesOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
updateKeyProperties(string, UpdateKeyPropertiesOptions)
The updateKeyProperties method changes specified properties of the latest version of an existing stored key. Properties that are not specified in the request are left unchanged. The value of a key itself cannot be changed. This operation requires the keys/set permission.
Example usage:
let keyName = "MyKey";
let client = new KeyClient(vaultUrl, credentials);
let key = await client.getKey(keyName);
let result = await client.updateKeyProperties(keyName, { enabled: false });
Updates the properties associated with a specified key in a given key vault.
function updateKeyProperties(name: string, options?: UpdateKeyPropertiesOptions): Promise<KeyVaultKey>Parameters
- name
-
string
The name of the key.
- options
- UpdateKeyPropertiesOptions
The optional parameters.
Returns
Promise<KeyVaultKey>
updateKeyRotationPolicy(string, KeyRotationPolicyProperties, UpdateKeyRotationPolicyOptions)
Updates the rotation policy of a Key Vault Key. This operation requires the keys/update permission.
Example usage:
let client = new KeyClient(vaultUrl, credentials);
const setPolicy = await client.updateKeyRotationPolicy("MyKey", myPolicy);
function updateKeyRotationPolicy(keyName: string, policy: KeyRotationPolicyProperties, options?: UpdateKeyRotationPolicyOptions): Promise<KeyRotationPolicy>Parameters
- keyName
-
string
The name of the key.
- policy
- KeyRotationPolicyProperties
- options
- UpdateKeyRotationPolicyOptions
The optional parameters.
Returns
Promise<KeyRotationPolicy>