SecretClient class

  • Reference
Package:
@azure/keyvault-secrets

The SecretClient provides methods to manage KeyVaultSecret in the Azure Key Vault. The client supports creating, retrieving, updating, deleting, purging, backing up, restoring and listing KeyVaultSecrets. The client also supports listing DeletedSecret for a soft-delete enabled Azure Key Vault.

Constructors

SecretClient(string, TokenCredential, SecretClientOptions)

Creates an instance of SecretClient.

Example usage:

import { SecretClient } from "@azure/keyvault-secrets";
import { DefaultAzureCredential } from "@azure/identity";

let vaultUrl = `https://<MY KEYVAULT HERE>.vault.azure.net`;
let credentials = new DefaultAzureCredential();

let client = new SecretClient(vaultUrl, credentials);

Properties

vaultUrl

The base URL to the vault

Methods

backupSecret(string, BackupSecretOptions)

Requests that a backup of the specified secret be downloaded to the client. All versions of the secret will be downloaded. This operation requires the secrets/backup permission.

Example usage:

let client = new SecretClient(url, credentials);
let backupResult = await client.backupSecret("MySecretName");

Backs up the specified secret.
beginDeleteSecret(string, BeginDeleteSecretOptions)

Deletes a secret stored in Azure Key Vault. This function returns a Long Running Operation poller that allows you to wait indefinitely until the secret is deleted.

This operation requires the secrets/delete permission.

Example usage:

const client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

const deletePoller = await client.beginDeleteSecret("MySecretName");

// Serializing the poller
const serialized = deletePoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginDeleteSecret("MySecretName", { resumeFrom: serialized });

// Waiting until it's done
const deletedSecret = await deletePoller.pollUntilDone();
console.log(deletedSecret);

Deletes a secret from a specified key vault.
beginRecoverDeletedSecret(string, BeginRecoverDeletedSecretOptions)

Recovers the deleted secret in the specified vault. This function returns a Long Running Operation poller that allows you to wait indefinitely until the secret is recovered.

This operation requires the secrets/recover permission.

Example usage:

const client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

const deletePoller = await client.beginDeleteSecret("MySecretName");
await deletePoller.pollUntilDone();

const recoverPoller = await client.beginRecoverDeletedSecret("MySecretName");

// Serializing the poller
const serialized = recoverPoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginRecoverDeletedSecret("MySecretName", { resumeFrom: serialized });

// Waiting until it's done
const deletedSecret = await recoverPoller.pollUntilDone();
console.log(deletedSecret);

Recovers the deleted secret to the latest version.
getDeletedSecret(string, GetDeletedSecretOptions)

The getDeletedSecret method returns the specified deleted secret along with its attributes. This operation requires the secrets/get permission.

Example usage:

let client = new SecretClient(url, credentials);
await client.getDeletedSecret("MyDeletedSecret");

Gets the specified deleted secret.
getSecret(string, GetSecretOptions)

The getSecret method is applicable to any secret stored in Azure Key Vault. This operation requires the secrets/get permission.

Example usage:

let client = new SecretClient(url, credentials);
let secret = await client.getSecret("MySecretName");

Get a specified secret from a given key vault.
listDeletedSecrets(ListDeletedSecretsOptions)

Iterates the deleted secrets in the vault. The full secret identifier and attributes are provided in the response. No values are returned for the secrets. This operations requires the secrets/list permission.

Example usage:

let client = new SecretClient(url, credentials);
for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("deleted secret: ", deletedSecret);
}

List all secrets in the vault.
listPropertiesOfSecrets(ListPropertiesOfSecretsOptions)

Iterates the latest version of all secrets in the vault. The full secret identifier and attributes are provided in the response. No values are returned for the secrets. This operations requires the secrets/list permission.

Example usage:

let client = new SecretClient(url, credentials);
for await (const secretProperties of client.listPropertiesOfSecrets()) {
  const secret = await client.getSecret(secretProperties.name);
  console.log("secret: ", secret);
}

List all secrets in the vault.
listPropertiesOfSecretVersions(string, ListPropertiesOfSecretVersionsOptions)

Iterates all versions of the given secret in the vault. The full secret identifier and attributes are provided in the response. No values are returned for the secrets. This operations requires the secrets/list permission.

Example usage:

let client = new SecretClient(url, credentials);
for await (const secretProperties of client.listPropertiesOfSecretVersions("MySecretName")) {
  const secret = await client.getSecret(secretProperties.name);
  console.log("secret version: ", secret);
}
purgeDeletedSecret(string, PurgeDeletedSecretOptions)

The purge deleted secret operation removes the secret permanently, without the possibility of recovery. This operation can only be enabled on a soft-delete enabled vault. This operation requires the secrets/purge permission.

Example usage:

const client = new SecretClient(url, credentials);
const deletePoller = await client.beginDeleteSecret("MySecretName");
await deletePoller.pollUntilDone();
await client.purgeDeletedSecret("MySecretName");

Permanently deletes the specified secret.
restoreSecretBackup(Uint8Array, RestoreSecretBackupOptions)

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

Example usage:

let client = new SecretClient(url, credentials);
let mySecretBundle = await client.backupSecret("MySecretName");
// ...
await client.restoreSecretBackup(mySecretBundle);

Restores a backed up secret to a vault.
setSecret(string, string, SetSecretOptions)

The setSecret method adds a secret or secret version to the Azure Key Vault. If the named secret already exists, Azure Key Vault creates a new version of that secret. This operation requires the secrets/set permission.

Example usage:

let client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

Adds a secret in a specified key vault.
updateSecretProperties(string, string, UpdateSecretPropertiesOptions)

The updateSecret method changes specified attributes of an existing stored secret. Properties that are not specified in the request are left unchanged. The value of a secret itself cannot be changed. This operation requires the secrets/set permission.

Example usage:

let secretName = "MySecretName";
let client = new SecretClient(url, credentials);
let secret = await client.getSecret(secretName);
await client.updateSecretProperties(secretName, secret.properties.version, { enabled: false });

Updates the attributes associated with a specified secret in a given key vault.

Constructor Details

SecretClient(string, TokenCredential, SecretClientOptions)

Creates an instance of SecretClient.

Example usage:

import { SecretClient } from "@azure/keyvault-secrets";
import { DefaultAzureCredential } from "@azure/identity";

let vaultUrl = `https://<MY KEYVAULT HERE>.vault.azure.net`;
let credentials = new DefaultAzureCredential();

let client = new SecretClient(vaultUrl, credentials);

new SecretClient(vaultUrl: string, credential: TokenCredential, pipelineOptions?: SecretClientOptions)

Parameters

vaultUrl

string

The base URL to the vault. You should validate that this URL references a valid Key Vault 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
SecretClientOptions

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

backupSecret(string, BackupSecretOptions)

Requests that a backup of the specified secret be downloaded to the client. All versions of the secret will be downloaded. This operation requires the secrets/backup permission.

Example usage:

let client = new SecretClient(url, credentials);
let backupResult = await client.backupSecret("MySecretName");

Backs up the specified secret.

function backupSecret(secretName: string, options?: BackupSecretOptions): Promise<undefined | Uint8Array>

Parameters

secretName

string

The name of the secret.

options
BackupSecretOptions

The optional parameters.

Returns

Promise<undefined | Uint8Array>

beginDeleteSecret(string, BeginDeleteSecretOptions)

Deletes a secret stored in Azure Key Vault. This function returns a Long Running Operation poller that allows you to wait indefinitely until the secret is deleted.

This operation requires the secrets/delete permission.

Example usage:

const client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

const deletePoller = await client.beginDeleteSecret("MySecretName");

// Serializing the poller
const serialized = deletePoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginDeleteSecret("MySecretName", { resumeFrom: serialized });

// Waiting until it's done
const deletedSecret = await deletePoller.pollUntilDone();
console.log(deletedSecret);

Deletes a secret from a specified key vault.

function beginDeleteSecret(name: string, options?: BeginDeleteSecretOptions): Promise<PollerLike<PollOperationState<DeletedSecret>, DeletedSecret>>

Parameters

name

string

options
BeginDeleteSecretOptions

The optional parameters.

Returns

Promise<PollerLike<PollOperationState<DeletedSecret>, DeletedSecret>>

beginRecoverDeletedSecret(string, BeginRecoverDeletedSecretOptions)

Recovers the deleted secret in the specified vault. This function returns a Long Running Operation poller that allows you to wait indefinitely until the secret is recovered.

This operation requires the secrets/recover permission.

Example usage:

const client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

const deletePoller = await client.beginDeleteSecret("MySecretName");
await deletePoller.pollUntilDone();

const recoverPoller = await client.beginRecoverDeletedSecret("MySecretName");

// Serializing the poller
const serialized = recoverPoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginRecoverDeletedSecret("MySecretName", { resumeFrom: serialized });

// Waiting until it's done
const deletedSecret = await recoverPoller.pollUntilDone();
console.log(deletedSecret);

Recovers the deleted secret to the latest version.

function beginRecoverDeletedSecret(name: string, options?: BeginRecoverDeletedSecretOptions): Promise<PollerLike<PollOperationState<SecretProperties>, SecretProperties>>

Parameters

name

string

options
BeginRecoverDeletedSecretOptions

The optional parameters.

Returns

Promise<PollerLike<PollOperationState<SecretProperties>, SecretProperties>>

getDeletedSecret(string, GetDeletedSecretOptions)

The getDeletedSecret method returns the specified deleted secret along with its attributes. This operation requires the secrets/get permission.

Example usage:

let client = new SecretClient(url, credentials);
await client.getDeletedSecret("MyDeletedSecret");

Gets the specified deleted secret.

function getDeletedSecret(secretName: string, options?: GetDeletedSecretOptions): Promise<DeletedSecret>

Parameters

secretName

string

The name of the secret.

options
GetDeletedSecretOptions

The optional parameters.

Returns

Promise<DeletedSecret>

getSecret(string, GetSecretOptions)

The getSecret method is applicable to any secret stored in Azure Key Vault. This operation requires the secrets/get permission.

Example usage:

let client = new SecretClient(url, credentials);
let secret = await client.getSecret("MySecretName");

Get a specified secret from a given key vault.

function getSecret(secretName: string, options?: GetSecretOptions): Promise<KeyVaultSecret>

Parameters

secretName

string

The name of the secret.

options
GetSecretOptions

The optional parameters.

Returns

Promise<KeyVaultSecret>

listDeletedSecrets(ListDeletedSecretsOptions)

Iterates the deleted secrets in the vault. The full secret identifier and attributes are provided in the response. No values are returned for the secrets. This operations requires the secrets/list permission.

Example usage:

let client = new SecretClient(url, credentials);
for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("deleted secret: ", deletedSecret);
}

List all secrets in the vault.

function listDeletedSecrets(options?: ListDeletedSecretsOptions): PagedAsyncIterableIterator<DeletedSecret, DeletedSecret[], PageSettings>

Parameters

options
ListDeletedSecretsOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<DeletedSecret, DeletedSecret[], PageSettings>

listPropertiesOfSecrets(ListPropertiesOfSecretsOptions)

Iterates the latest version of all secrets in the vault. The full secret identifier and attributes are provided in the response. No values are returned for the secrets. This operations requires the secrets/list permission.

Example usage:

let client = new SecretClient(url, credentials);
for await (const secretProperties of client.listPropertiesOfSecrets()) {
  const secret = await client.getSecret(secretProperties.name);
  console.log("secret: ", secret);
}

List all secrets in the vault.

function listPropertiesOfSecrets(options?: ListPropertiesOfSecretsOptions): PagedAsyncIterableIterator<SecretProperties, SecretProperties[], PageSettings>

Parameters

options
ListPropertiesOfSecretsOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<SecretProperties, SecretProperties[], PageSettings>

listPropertiesOfSecretVersions(string, ListPropertiesOfSecretVersionsOptions)

Iterates all versions of the given secret in the vault. The full secret identifier and attributes are provided in the response. No values are returned for the secrets. This operations requires the secrets/list permission.

Example usage:

let client = new SecretClient(url, credentials);
for await (const secretProperties of client.listPropertiesOfSecretVersions("MySecretName")) {
  const secret = await client.getSecret(secretProperties.name);
  console.log("secret version: ", secret);
}

function listPropertiesOfSecretVersions(secretName: string, options?: ListPropertiesOfSecretVersionsOptions): PagedAsyncIterableIterator<SecretProperties, SecretProperties[], PageSettings>

Parameters

secretName

string

Name of the secret to fetch versions for.

options
ListPropertiesOfSecretVersionsOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<SecretProperties, SecretProperties[], PageSettings>

purgeDeletedSecret(string, PurgeDeletedSecretOptions)

The purge deleted secret operation removes the secret permanently, without the possibility of recovery. This operation can only be enabled on a soft-delete enabled vault. This operation requires the secrets/purge permission.

Example usage:

const client = new SecretClient(url, credentials);
const deletePoller = await client.beginDeleteSecret("MySecretName");
await deletePoller.pollUntilDone();
await client.purgeDeletedSecret("MySecretName");

Permanently deletes the specified secret.

function purgeDeletedSecret(secretName: string, options?: PurgeDeletedSecretOptions): Promise<void>

Parameters

secretName

string

The name of the secret.

options
PurgeDeletedSecretOptions

The optional parameters.

Returns

Promise<void>

restoreSecretBackup(Uint8Array, RestoreSecretBackupOptions)

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

Example usage:

let client = new SecretClient(url, credentials);
let mySecretBundle = await client.backupSecret("MySecretName");
// ...
await client.restoreSecretBackup(mySecretBundle);

Restores a backed up secret to a vault.

function restoreSecretBackup(secretBundleBackup: Uint8Array, options?: RestoreSecretBackupOptions): Promise<SecretProperties>

Parameters

secretBundleBackup

Uint8Array

The backup blob associated with a secret bundle.

options
RestoreSecretBackupOptions

The optional parameters.

Returns

Promise<SecretProperties>

setSecret(string, string, SetSecretOptions)

The setSecret method adds a secret or secret version to the Azure Key Vault. If the named secret already exists, Azure Key Vault creates a new version of that secret. This operation requires the secrets/set permission.

Example usage:

let client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

Adds a secret in a specified key vault.

function setSecret(secretName: string, value: string, options?: SetSecretOptions): Promise<KeyVaultSecret>

Parameters

secretName

string

The name of the secret.

value

string

The value of the secret.

options
SetSecretOptions

The optional parameters.

Returns

Promise<KeyVaultSecret>

updateSecretProperties(string, string, UpdateSecretPropertiesOptions)

The updateSecret method changes specified attributes of an existing stored secret. Properties that are not specified in the request are left unchanged. The value of a secret itself cannot be changed. This operation requires the secrets/set permission.

Example usage:

let secretName = "MySecretName";
let client = new SecretClient(url, credentials);
let secret = await client.getSecret(secretName);
await client.updateSecretProperties(secretName, secret.properties.version, { enabled: false });

Updates the attributes associated with a specified secret in a given key vault.

function updateSecretProperties(secretName: string, secretVersion: string, options?: UpdateSecretPropertiesOptions): Promise<SecretProperties>

Parameters

secretName

string

The name of the secret.

secretVersion

string

The version of the secret.

options
UpdateSecretPropertiesOptions

The optional parameters.

Returns

Promise<SecretProperties>