KeyClient class

The KeyClient provides methods to manage <xref: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 <xref:DeletedKey> for a soft-delete enabled Azure Key Vault.

Constructors

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

Properties

vaultUrl

The base URL to the vault

Methods

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");
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);
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);
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" });
createKey(string, KeyType, 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");
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 });
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");
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");
importKey(string, JsonWebKey, 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);
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);
}
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);
}
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);
}
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");
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);
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(url, credentials);
let key = await client.getKey(keyName);
let result = await client.updateKeyProperties(keyName, key.properties.version, { enabled: false });

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

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

Property Details

vaultUrl

The base URL to the vault

vaultUrl: string

Property 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");
function backupKey(name: string, options?: BackupKeyOptions)

Parameters

name

string

The name of the key.

Returns

Promise<Uint8Array | undefined>

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);
function beginDeleteKey(name: string, options?: BeginDeleteKeyOptions)

Parameters

name

string

The name of the key.

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);
function beginRecoverDeletedKey(name: string, options?: BeginRecoverDeletedKeyOptions)

Parameters

name

string

The name of the deleted key.

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" });
function createEcKey(name: string, options?: CreateEcKeyOptions)

Parameters

name

string

The name of the key.

Returns

Promise<KeyVaultKey>

createKey(string, KeyType, 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");
function createKey(name: string, keyType: KeyType, options?: CreateKeyOptions)

Parameters

name

string

The name of the key.

keyType
KeyType

The type of the key. One of the following: 'EC', 'EC-HSM', 'RSA', 'RSA-HSM', 'oct'.

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 });
function createRsaKey(name: string, options?: CreateRsaKeyOptions)

Parameters

name

string

The name of the key.

Returns

Promise<KeyVaultKey>

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");
function getDeletedKey(name: string, options?: GetDeletedKeyOptions)

Parameters

name

string

The name of the key.

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");
function getKey(name: string, options?: GetKeyOptions)

Parameters

name

string

The name of the key.

options
GetKeyOptions

Returns

Promise<KeyVaultKey>

importKey(string, JsonWebKey, 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);
function importKey(name: string, key: JsonWebKey, options?: ImportKeyOptions)

Parameters

name

string

Name for the imported key.

key
JsonWebKey

The JSON web key.

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);
}
function listDeletedKeys(options?: ListDeletedKeysOptions)

Parameters

Returns

PagedAsyncIterableIterator<DeletedKey>

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);
}
function listPropertiesOfKeys(options?: ListPropertiesOfKeysOptions)

Parameters

Returns

PagedAsyncIterableIterator<KeyProperties>

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)

Parameters

name

string

Name of the key to fetch versions for

Returns

PagedAsyncIterableIterator<KeyProperties>

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");
function purgeDeletedKey(name: string, options?: PurgeDeletedKeyOptions)

Parameters

name

string

The name of the key.

Returns

Promise<void>

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);
function restoreKeyBackup(backup: Uint8Array, options?: RestoreKeyBackupOptions)

Parameters

backup

Uint8Array

The backup blob associated with a key bundle.

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(url, credentials);
let key = await client.getKey(keyName);
let result = await client.updateKeyProperties(keyName, key.properties.version, { enabled: false });
function updateKeyProperties(name: string, keyVersion: string, options?: UpdateKeyPropertiesOptions)

Parameters

name

string

The name of the key.

keyVersion

string

The version of the key.

Returns

Promise<KeyVaultKey>