Share via

KeyClient class

Package:
@azure/keyvault-keys

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

KeyClient(string, TokenCredential, KeyClientOptions)

Creates an instance of KeyClient.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`; // or `https://${vaultName}.managedhsm.azure.net` for managed HSM.

// Lastly, create our keys client and connect to the service
const client = new KeyClient(url, credential);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const backupContents = await client.backupKey(keyName);

Backs up the specified key.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const poller = await client.beginDeleteKey(keyName);
await poller.pollUntilDone();

Deletes a key from a specified key vault.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const deletePoller = await client.beginDeleteKey(keyName);
await deletePoller.pollUntilDone();

const recoverPoller = await client.beginRecoverDeletedKey(keyName);
const recoveredKey = await recoverPoller.pollUntilDone();

Recovers the deleted key to the latest version.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";
const result = await client.createEcKey(keyName, { curve: "P-256" });
console.log("result: ", result);

Creates a new key, stores it, then returns key parameters and properties to the client.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";
const result = await client.createKey(keyName, "RSA");
console.log("result: ", result);

Creates a new key, stores it, then returns key parameters and properties to the client.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";
const result = await client.createOctKey("MyKey", { hsm: true });
console.log("result: ", result);

Creates a new key, stores it, then returns key parameters and properties to the client.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";
const result = await client.createRsaKey("MyKey", { keySize: 2048 });
console.log("result: ", result);

Creates a new key, stores it, then returns key parameters and properties to the client.
getCryptographyClient(string, GetCryptographyClientOptions)

Gets a CryptographyClient for the given key.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

// Get a cryptography client for a given key
const cryptographyClient = client.getCryptographyClient("MyKey");
getDeletedKey(string, GetDeletedKeyOptions)

The getDeletedKey method returns the specified deleted key along with its properties. This operation requires the keys/get permission.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

await client.getDeletedKey(keyName);

Gets the specified deleted key.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const latestKey = await client.getKey(keyName);
console.log(`Latest version of the key ${keyName}: `, latestKey);

const specificKey = await client.getKey(keyName, { version: latestKey.properties.version! });
console.log(`The key ${keyName} at the version ${latestKey.properties.version!}: `, specificKey);

Get a specified key from a given key vault.
getKeyAttestation(string, GetKeyAttestationOptions)

The getKeyAttestation method gets a specified key and its attestation blob and is applicable to any key stored in Azure Key Vault Managed HSM. This operation requires the keys/get permission.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT MANAGED HSM NAME>";
const url = `https://${vaultName}.managedhsm.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const latestKey = await client.getKeyAttestation(keyName);
console.log(`Latest version of the key ${keyName}: `, latestKey);

const specificKey = await client.getKeyAttestation(keyName, {
  version: latestKey.properties.version!,
});
console.log(`The key ${keyName} at the version ${latestKey.properties.version!}: `, specificKey);

Get a specified key from a given key vault.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const result = await client.getKeyRotationPolicy(keyName);
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const bytes = await client.getRandomBytes(10);
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const jsonWebKey = {
  kty: "RSA",
  kid: "test-key-123",
  use: "sig",
  alg: "RS256",
  n: new Uint8Array([112, 34, 56, 98, 123, 244, 200, 99]),
  e: new Uint8Array([1, 0, 1]),
  d: new Uint8Array([45, 67, 89, 23, 144, 200, 76, 233]),
  p: new Uint8Array([34, 89, 100, 77, 204, 56, 29, 77]),
  q: new Uint8Array([78, 99, 201, 45, 188, 34, 67, 90]),
  dp: new Uint8Array([23, 45, 78, 56, 200, 144, 32, 67]),
  dq: new Uint8Array([12, 67, 89, 144, 99, 56, 23, 45]),
  qi: new Uint8Array([78, 90, 45, 201, 34, 67, 120, 55]),
};

const result = await client.importKey("MyKey", jsonWebKey);

Imports an externally created key, stores it, and returns key parameters and properties to the client.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

for await (const keyProperties of client.listPropertiesOfKeys()) {
  console.log("Key properties: ", keyProperties);
}

for await (const deletedKey of client.listDeletedKeys()) {
  console.log("Deleted: ", deletedKey);
}

for await (const versionProperties of client.listPropertiesOfKeyVersions(keyName)) {
  console.log("Version properties: ", versionProperties);
}

List all keys in the vault
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

for await (const keyProperties of client.listPropertiesOfKeys()) {
  console.log("Key properties: ", keyProperties);
}

for await (const deletedKey of client.listDeletedKeys()) {
  console.log("Deleted: ", deletedKey);
}

for await (const versionProperties of client.listPropertiesOfKeyVersions(keyName)) {
  console.log("Version properties: ", versionProperties);
}

List all keys in the vault
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

for await (const keyProperties of client.listPropertiesOfKeys()) {
  console.log("Key properties: ", keyProperties);
}

for await (const deletedKey of client.listDeletedKeys()) {
  console.log("Deleted: ", deletedKey);
}

for await (const versionProperties of client.listPropertiesOfKeyVersions(keyName)) {
  console.log("Version properties: ", versionProperties);
}
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const deletePoller = await client.beginDeleteKey(keyName);
await deletePoller.pollUntilDone();

await client.purgeDeletedKey(keyName);

Permanently deletes the specified key.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const result = await client.releaseKey("myKey", "<attestation-target>");
restoreKeyBackup(Uint8Array, RestoreKeyBackupOptions)

Restores a backed up key, and all its versions, to a vault. This operation requires the keys/restore permission.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const backupContents = await client.backupKey(keyName);

const key = await client.restoreKeyBackup(backupContents);

Restores a backed up key to a vault.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

// Set the key's automated rotation policy to rotate the key 30 days before expiry.
const policy = await client.updateKeyRotationPolicy(keyName, {
  lifetimeActions: [
    {
      action: "Rotate",
      timeBeforeExpiry: "P30D",
    },
  ],
  // You may also specify the duration after which any newly rotated key will expire.
  // In this case, any new key versions will expire after 90 days.
  expiresIn: "P90D",
});

// You can get the current key rotation policy of a given key by calling the getKeyRotationPolicy method.
const currentPolicy = await client.getKeyRotationPolicy(keyName);

// Finally, you can rotate a key on-demand by creating a new version of the given key.
const rotatedKey = await client.rotateKey(keyName);
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const result = await client.createKey(keyName, "RSA");
await client.updateKeyProperties(keyName, result.properties.version, {
  enabled: false,
});

Updates the properties associated with a specified key in a given key vault.
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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const result = await client.createKey(keyName, "RSA");
await client.updateKeyProperties(keyName, result.properties.version, {
  enabled: false,
});

Updates the properties associated with a specified key in a given key vault.
updateKeyRotationPolicy(string, KeyRotationPolicyProperties, UpdateKeyRotationPolicyOptions)

Updates the rotation policy of a Key Vault Key. This operation requires the keys/update permission.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const myPolicy = await client.getKeyRotationPolicy(keyName);

const setPolicy = await client.updateKeyRotationPolicy(keyName, myPolicy);

Constructor Details

KeyClient(string, TokenCredential, KeyClientOptions)

Creates an instance of KeyClient.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`; // or `https://${vaultName}.managedhsm.azure.net` for managed HSM.

// Lastly, create our keys client and connect to the service
const client = new KeyClient(url, credential);

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: 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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const backupContents = await client.backupKey(keyName);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const poller = await client.beginDeleteKey(keyName);
await poller.pollUntilDone();

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const deletePoller = await client.beginDeleteKey(keyName);
await deletePoller.pollUntilDone();

const recoverPoller = await client.beginRecoverDeletedKey(keyName);
const recoveredKey = await recoverPoller.pollUntilDone();

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";
const result = await client.createEcKey(keyName, { curve: "P-256" });
console.log("result: ", result);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";
const result = await client.createKey(keyName, "RSA");
console.log("result: ", result);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";
const result = await client.createOctKey("MyKey", { hsm: true });
console.log("result: ", result);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";
const result = await client.createRsaKey("MyKey", { keySize: 2048 });
console.log("result: ", result);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

// Get a cryptography client for a given key
const cryptographyClient = client.getCryptographyClient("MyKey");

function getCryptographyClient(keyName: string, options?: GetCryptographyClientOptions): CryptographyClient

Parameters

keyName

string

options
GetCryptographyClientOptions

Returns

CryptographyClient

getDeletedKey(string, GetDeletedKeyOptions)

The getDeletedKey method returns the specified deleted key along with its properties. This operation requires the keys/get permission.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

await client.getDeletedKey(keyName);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const latestKey = await client.getKey(keyName);
console.log(`Latest version of the key ${keyName}: `, latestKey);

const specificKey = await client.getKey(keyName, { version: latestKey.properties.version! });
console.log(`The key ${keyName} at the version ${latestKey.properties.version!}: `, specificKey);

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>

getKeyAttestation(string, GetKeyAttestationOptions)

The getKeyAttestation method gets a specified key and its attestation blob and is applicable to any key stored in Azure Key Vault Managed HSM. This operation requires the keys/get permission.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT MANAGED HSM NAME>";
const url = `https://${vaultName}.managedhsm.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const latestKey = await client.getKeyAttestation(keyName);
console.log(`Latest version of the key ${keyName}: `, latestKey);

const specificKey = await client.getKeyAttestation(keyName, {
  version: latestKey.properties.version!,
});
console.log(`The key ${keyName} at the version ${latestKey.properties.version!}: `, specificKey);

Get a specified key from a given key vault.

function getKeyAttestation(name: string, options?: GetKeyAttestationOptions): Promise<KeyVaultKey>

Parameters

name

string

The name of the key.

options
GetKeyAttestationOptions

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const result = await client.getKeyRotationPolicy(keyName);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const 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, 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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const jsonWebKey = {
  kty: "RSA",
  kid: "test-key-123",
  use: "sig",
  alg: "RS256",
  n: new Uint8Array([112, 34, 56, 98, 123, 244, 200, 99]),
  e: new Uint8Array([1, 0, 1]),
  d: new Uint8Array([45, 67, 89, 23, 144, 200, 76, 233]),
  p: new Uint8Array([34, 89, 100, 77, 204, 56, 29, 77]),
  q: new Uint8Array([78, 99, 201, 45, 188, 34, 67, 90]),
  dp: new Uint8Array([23, 45, 78, 56, 200, 144, 32, 67]),
  dq: new Uint8Array([12, 67, 89, 144, 99, 56, 23, 45]),
  qi: new Uint8Array([78, 90, 45, 201, 34, 67, 120, 55]),
};

const result = await client.importKey("MyKey", jsonWebKey);

Imports an externally created key, stores it, and returns key parameters and properties to the client.

function importKey(name: string, key: JsonWebKey, 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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

for await (const keyProperties of client.listPropertiesOfKeys()) {
  console.log("Key properties: ", keyProperties);
}

for await (const deletedKey of client.listDeletedKeys()) {
  console.log("Deleted: ", deletedKey);
}

for await (const versionProperties of client.listPropertiesOfKeyVersions(keyName)) {
  console.log("Version properties: ", versionProperties);
}

List all keys in the vault

function listDeletedKeys(options?: ListDeletedKeysOptions): PagedAsyncIterableIterator<DeletedKey, DeletedKey[], PageSettings>

Parameters

options
ListDeletedKeysOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<DeletedKey, DeletedKey[], PageSettings>

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

for await (const keyProperties of client.listPropertiesOfKeys()) {
  console.log("Key properties: ", keyProperties);
}

for await (const deletedKey of client.listDeletedKeys()) {
  console.log("Deleted: ", deletedKey);
}

for await (const versionProperties of client.listPropertiesOfKeyVersions(keyName)) {
  console.log("Version properties: ", versionProperties);
}

List all keys in the vault

function listPropertiesOfKeys(options?: ListPropertiesOfKeysOptions): PagedAsyncIterableIterator<KeyProperties, KeyProperties[], PageSettings>

Parameters

options
ListPropertiesOfKeysOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<KeyProperties, KeyProperties[], PageSettings>

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

for await (const keyProperties of client.listPropertiesOfKeys()) {
  console.log("Key properties: ", keyProperties);
}

for await (const deletedKey of client.listDeletedKeys()) {
  console.log("Deleted: ", deletedKey);
}

for await (const versionProperties of client.listPropertiesOfKeyVersions(keyName)) {
  console.log("Version properties: ", versionProperties);
}

function listPropertiesOfKeyVersions(name: string, options?: ListPropertiesOfKeyVersionsOptions): PagedAsyncIterableIterator<KeyProperties, KeyProperties[], PageSettings>

Parameters

name

string

Name of the key to fetch versions for

options
ListPropertiesOfKeyVersionsOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<KeyProperties, KeyProperties[], PageSettings>

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const deletePoller = await client.beginDeleteKey(keyName);
await deletePoller.pollUntilDone();

await client.purgeDeletedKey(keyName);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const result = await client.releaseKey("myKey", "<attestation-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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const backupContents = await client.backupKey(keyName);

const 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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

// Set the key's automated rotation policy to rotate the key 30 days before expiry.
const policy = await client.updateKeyRotationPolicy(keyName, {
  lifetimeActions: [
    {
      action: "Rotate",
      timeBeforeExpiry: "P30D",
    },
  ],
  // You may also specify the duration after which any newly rotated key will expire.
  // In this case, any new key versions will expire after 90 days.
  expiresIn: "P90D",
});

// You can get the current key rotation policy of a given key by calling the getKeyRotationPolicy method.
const currentPolicy = await client.getKeyRotationPolicy(keyName);

// Finally, you can rotate a key on-demand by creating a new version of the given key.
const rotatedKey = await client.rotateKey(keyName);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const result = await client.createKey(keyName, "RSA");
await client.updateKeyProperties(keyName, result.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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const result = await client.createKey(keyName, "RSA");
await client.updateKeyProperties(keyName, result.properties.version, {
  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:

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new KeyClient(url, credential);

const keyName = "MyKeyName";

const myPolicy = await client.getKeyRotationPolicy(keyName);

const setPolicy = await client.updateKeyRotationPolicy(keyName, 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>