SecretClient (Azure SDK for Java Reference Documentation)

java.lang.Object
- com.azure.core.ServiceClient
- - com.azure.keyvault.SecretClient

```
public final class SecretClient
extends ServiceClient
```
The SecretClient provides synchronous methods to manage secrets in the Azure Key Vault. The client supports creating, retrieving, updating, deleting, purging, backing up, restoring and listing the secrets. The client also supports listing deleted secrets for a soft-delete enabled Azure Key Vault.
Samples to construct the client
```
 SecretClient.builder()
   .endpoint("https://myvault.vault.azure.net/")
   .credential(keyVaultCredential)
   .build()
 
```
See Also:

SecretClientBuilder

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Response<byte[]>`	`backupSecret(String name)` Requests a backup of the specified secret be downloaded to the client.
`static SecretClientBuilder`	`builder()` Creates a builder that can configure options for the SecretClient before creating an instance of it.
`Response<DeletedSecret>`	`deleteSecret(String name)` Deletes a secret from the key vault.
`Response<DeletedSecret>`	`getDeletedSecret(String name)` The get deleted secret operation returns the secrets that have been deleted for a vault enabled for soft-delete.
`Response<Secret>`	`getSecret(SecretBase secretBase)` Get the secret which represents `secretBase` from the key vault.
`Response<Secret>`	`getSecret(String name)` Get the latest version of the specified secret from the key vault.
`Response<Secret>`	`getSecret(String name, String version)` Get the latest version of the specified secret from the key vault.
`List<DeletedSecret>`	`listDeletedSecrets()` Lists `deleted secrets` of the key vault.
`List<SecretBase>`	`listSecrets()` List the secrets in the key vault.
`List<SecretBase>`	`listSecretVersions(String name)` List all versions of the specified secret.
`VoidResponse`	`purgeDeletedSecret(String name)` The purge deleted secret operation removes the secret permanently, without the possibility of recovery.
`Response<Secret>`	`recoverDeletedSecret(String name)` Recovers the deleted secret in the key vault to its latest version and can only be performed on a soft-delete enabled vault.
`Response<Secret>`	`restoreSecret(byte[] backup)` Restores a backed up secret, and all its versions, to a vault.
`Response<Secret>`	`setSecret(Secret secret)` The set operation adds a secret to the Azure Key Vault.
`Response<Secret>`	`setSecret(String name, String value)` The set operation adds a secret to the Azure Key Vault.
`Response<SecretBase>`	`updateSecret(SecretBase secret)` Updates the attributes associated with the specified secret, but not the value of the specified secret in the key vault.

Methods inherited from class com.azure.core.ServiceClient
httpPipeline

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - builder
```
public static SecretClientBuilder builder()
```
    Creates a builder that can configure options for the SecretClient before creating an instance of it.
    
    Returns:
    
    A new builder to create a SecretClient from.
  - setSecret
```
public Response<Secret> setSecret(Secret secret)
```
    The set operation adds a secret to the Azure Key Vault. If the named secret already exists, a new version of the secret is created in the key vault. This operation requires the secrets/set permission.
    The Secret is required. The expires, contentType and notBefore values in secret are optional. The enabled field is set to true by key vault, if not specified.
    
    Code Samples
    
    Creates a new secret which expires in 60 days in the key vault. Prints out the details of the newly created secret returned in the response.
```
 Secret secret = new Secret("secretName", "secretValue")
   .expires(OffsetDateTime.now.plusDays(60));

 Secret retSecret = secretClient.setSecret(keySecret).value();
 System.out.printf("Secret is created with name %s and value %s \n", retSecret.name(), retSecret.value());
 
```
    Parameters:
    
    secret - The Secret object containing information about the secret and its properties. The properties secret.name and secret.value must be non null.
    
    Returns:
    
    A Response whose value contains the created secret.
    
    Throws:
    
    NullPointerException - if secret is null.
    
    ResourceModifiedException - if secret is malformed.
    
    HttpRequestException - if name or value is empty string.
  - setSecret
```
public Response<Secret> setSecret(String name,
                                  String value)
```
    The set operation adds a secret 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.
    Code Samples
    
    Creates a new secret in the key vault. Prints out the details of the newly created secret returned in the response.
```
 Secret secret = secretClient.setSecret("secretName", "secretValue").value();
 System.out.printf("Secret is created with name %s and value %s \n", secret.name(), secret.value());
 
```
    Parameters:
    
    name - The name of the secret. It is required and cannot be null.
    
    value - The value of the secret. It is required and cannot be null.
    
    Returns:
    
    A Response whose value contains the created secret.
    
    Throws:
    
    ResourceModifiedException - if invalid name or value is specified.
    
    HttpRequestException - if name or value is empty string.
  - getSecret
```
public Response<Secret> getSecret(String name,
                                  String version)
```
    Get the latest version of the specified secret from the key vault. The get operation is applicable to any secret stored in Azure Key Vault. This operation requires the secrets/get permission.
    Code Samples
    
    Gets a specific version of the secret in the key vault. Prints out the details of the returned secret.
```
 String secretVersion = "6A385B124DEF4096AF1361A85B16C204";
 Secret secretWithVersion = secretClient.getSecret("secretName", secretVersion).value();
 System.out.printf("Secret is returned with name %s and value %s \n", secretWithVersion.name(), secretWithVersion.value());
 
```
    Parameters:
    
    name - The name of the secret, cannot be null.
    
    version - The version of the secret to retrieve. If this is an empty String or null, this call is equivalent to calling SecretClient.getSecret(String), with the latest version being retrieved.
    
    Returns:
    
    A Response whose value contains the requested secret.
    
    Throws:
    
    ResourceNotFoundException - when a secret with name and version doesn't exist in the key vault.
    
    HttpRequestException - if name or version is empty string.
  - getSecret
```
public Response<Secret> getSecret(SecretBase secretBase)
```
    Get the secret which represents secretBase from the key vault. The get operation is applicable to any secret stored in Azure Key Vault. This operation requires the secrets/get permission.
    The list operations SecretClient.listSecrets() and SecretClient.listSecretVersions(String) return the List containing base secret as output excluding the include the value of the secret. This operation can then be used to get the full secret with its value from secretBase.
```
secretClient.listSecrets()
    .stream()
    .map(secretClient::getSecret)
    .forEach(secretResponse ->
        System.out.printf("Secret is returned with name %s and value %s %n",
            secretResponse.value().name(), secretResponse.value().value()));
```
    Parameters:
    
    secretBase - The base secret holding attributes of the secret being requested.
    
    Returns:
    
    A Response whose value contains the requested secret.
    
    Throws:
    
    ResourceNotFoundException - when a secret with name and version doesn't exist in the key vault.
    
    HttpRequestException - if name or version is empty string.
  - getSecret
```
public Response<Secret> getSecret(String name)
```
    Get the latest version of the specified secret from the key vault. The get operation is applicable to any secret stored in Azure Key Vault. This operation requires the secrets/get permission.
    Code Samples
    
    Gets the latest version of the secret in the key vault. Prints out the details of the returned secret.
```
 Secret secret = secretClient.getSecret("secretName").value();
 System.out.printf("Secret is returned with name %s and value %s \n", secret.name(), secret.value());
 
```
    Parameters:
    
    name - The name of the secret.
    
    Returns:
    
    A Response whose Response.value() contains the requested Secret.
    
    Throws:
    
    ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
    
    HttpRequestException - if name is empty string.
  - updateSecret
```
public Response<SecretBase> updateSecret(SecretBase secret)
```
    Updates the attributes associated with the specified secret, but not the value of the specified secret in the key vault. The update operation changes specified attributes of an existing stored secret and attributes 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.
    The secret is required and its fields name and version cannot be null.
    
    Code Samples
    
    Gets the latest version of the secret, changes its expiry time and the updates the secret in the key vault.
```
 Secret secret = secretClient.getSecret("secretName").value();
 secret.expires(OffsetDateTime.now().plusDays(60));
 SecretBase updatedSecretBase = secretClient.updateSecret(secret).value();
 Secret updatedSecret = secretClient.getSecret(updatedSecretBase.name()).value();
 
```
    Parameters:
    
    secret - The base secret object with updated properties.
    
    Returns:
    
    A Response whose value contains the updated secret.
    
    Throws:
    
    NullPointerException - if secret is null.
    
    ResourceNotFoundException - when a secret with name and version doesn't exist in the key vault.
    
    HttpRequestException - if name or version is empty string.
  - deleteSecret
```
public Response<DeletedSecret> deleteSecret(String name)
```
    Deletes a secret from the key vault. If soft-delete is enabled on the key vault then the secret is placed in the deleted state and requires to be purged for permanent deletion else the secret is permanently deleted. The delete operation applies to any secret stored in Azure Key Vault but it cannot be applied to an individual version of a secret. This operation requires the secrets/delete permission.
    Code Samples
    
    Deletes the secret from the keyvault. Prints out the recovery id of the deleted secret returned in the response.
```
 DeletedSecret deletedSecret = secretClient.deleteSecret("secretName").value();
 System.out.printf("Deleted Secret's Recovery Id %s", deletedSecret.recoveryId()));
 
```
    Parameters:
    
    name - The name of the secret to be deleted.
    
    Returns:
    
    A Response whose value contains the deleted secret.
    
    Throws:
    
    ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
    
    HttpRequestException - when a secret with name is empty string.
  - getDeletedSecret
```
public Response<DeletedSecret> getDeletedSecret(String name)
```
    The get deleted secret operation returns the secrets that have been deleted for a vault enabled for soft-delete. This operation requires the secrets/list permission.
    Code Samples
    
    Gets the deleted secret from the key vault enabled for soft-delete. Prints out the details of the deleted secret returned in the response.
```
 //Assuming secret is deleted on a soft-delete enabled key vault.
 DeletedSecret deletedSecret = secretClient.getDeletedSecret("secretName").value();
 System.out.printf("Deleted Secret with recovery Id %s \n", deletedSecret.recoveryId());
 
```
    Parameters:
    
    name - The name of the deleted secret.
    
    Returns:
    
    A Response whose value contains the deleted secret.
    
    Throws:
    
    ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
    
    HttpRequestException - when a secret with name is empty string.
  - purgeDeletedSecret
```
public VoidResponse purgeDeletedSecret(String name)
```
    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.
    Code Samples
    
    Purges the deleted secret from the key vault enabled for soft-delete. Prints out the status code from the server response.
```
 //Assuming secret is deleted on a soft-delete enabled key vault.
 VoidResponse purgeResponse = secretClient.purgeDeletedSecret("deletedSecretName");
 System.out.printf("Purge Status Code: %d", purgeResponse.statusCode());
 
```
    Parameters:
    
    name - The name of the secret.
    
    Returns:
    
    A VoidResponse.
    
    Throws:
    
    ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
    
    HttpRequestException - when a secret with name is empty string.
  - recoverDeletedSecret
```
public Response<Secret> recoverDeletedSecret(String name)
```
    Recovers the deleted secret in the key vault to its latest version and can only be performed on a soft-delete enabled vault. This operation requires the secrets/recover permission.
    Code Samples
    
    Recovers the deleted secret from the key vault enabled for soft-delete. Prints out the details of the recovered secret returned in the response.
```
 //Assuming secret is deleted on a soft-delete enabled key vault.
 Secret recoveredSecret =  secretClient.recoverDeletedSecret("deletedSecretName").value();
 System.out.printf("Recovered Secret with name %s", recoveredSecret.name());
 
```
    Parameters:
    
    name - The name of the deleted secret to be recovered.
    
    Returns:
    
    A Response whose value contains the recovered secret.
    
    Throws:
    
    ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
    
    HttpRequestException - when a secret with name is empty string.
  - backupSecret
```
public Response<byte[]> backupSecret(String name)
```
    Requests 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.
    Code Samples
    
    Backs up the secret from the key vault and prints out the length of the secret's backup byte array returned in the response
```
 byte[] secretBackup = secretClient.backupSecret("secretName").value();
 System.out.printf("Secret's Backup Byte array's length %s", secretBackup.length);
 
```
    Parameters:
    
    name - The name of the secret.
    
    Returns:
    
    A Response whose value contains the backed up secret blob.
    
    Throws:
    
    ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
    
    HttpRequestException - when a secret with name is empty string.
  - restoreSecret
```
public Response<Secret> restoreSecret(byte[] backup)
```
    Restores a backed up secret, and all its versions, to a vault. This operation requires the secrets/restore permission.
    Code Samples
    
    Restores the secret in the key vault from its backup byte array. Prints out the details of the restored secret returned in the response.
```
 //Pass the secret backup byte array of the secret to be restored.
 Secret restoredSecret = secretClient.restoreSecret(secretBackupByteArray).value();
 System.out.printf("Restored Secret with name %s and value %s", restoredSecret.name(), restoredSecret.value());
 
```
    Parameters:
    
    backup - The backup blob associated with the secret.
    
    Returns:
    
    A Response whose value contains the restored secret.
    
    Throws:
    
    ResourceModifiedException - when backup blob is malformed.
  - listSecrets
```
public List<SecretBase> listSecrets()
```
    List the secrets in the key vault. The list Secrets operation is applicable to the entire vault. The individual secret response in the list is represented by SecretBase as only the base secret identifier and its attributes are provided in the response. The secret values and individual secret versions are not listed in the response. This operation requires the secrets/list permission.
    It is possible to get full secrets with values from this information. Loop over the secret and call SecretClient.getSecret(SecretBase baseSecret) . This will return the secret with value included of its latest version.
```
 secretClient.listSecrets().stream().map(secretClient::getSecret).forEach(secretResponse ->
   System.out.printf("Received secret with name %s and value %s", secretResponse.value().name(), secretResponse.value().value()));
 
```
    Returns:
    
    A List containing SecretBase of all the secrets in the vault. The SecretBase contains all the information about the secret, except its value.
  - listDeletedSecrets
```
public List<DeletedSecret> listDeletedSecrets()
```
    Lists deleted secrets of the key vault. The get deleted secrets operation returns the secrets that have been deleted for a vault enabled for soft-delete. This operation requires the secrets/list permission.
    Code Samples
    
    Lists the deleted secrets in the key vault and for each deleted secret prints out its recovery id.
```
 secretClient.listDeletedSecrets().stream().forEach(deletedSecret ->
   System.out.printf("Deleted secret's recovery Id %s", deletedSecret.recoveryId()));
 
```
    Returns:
    
    A List containing all of the deleted secrets in the vault.
  - listSecretVersions
```
public List<SecretBase> listSecretVersions(String name)
```
    List all versions of the specified secret. The individual secret response in the list is represented by SecretBase as only the base secret identifier and its attributes are provided in the response. The secret values are not provided in the response. This operation requires the secrets/list permission.
    It is possible to get full Secrets with values for each version from this information. Loop over the secret and call SecretClient.getSecret(SecretBase) . This will return the Secret secrets with values included of the specified versions.
```
 secretClient.listSecretVersions("secretName").stream().map(secretClient::getSecret).forEach(secretResponse ->
   System.out.printf("Received secret's version with name %s and value %s", secretResponse.value().name(), secretResponse.value().value()));
 
```
    Parameters:
    
    name - The name of the secret.
    
    Returns:
    
    A List containing SecretBase of all the versions of the specified secret in the vault. List is empty if secret with name does not exist in key vault
    
    Throws:
    
    ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
    
    HttpRequestException - when a secret with name is empty string.

Class SecretClient

Method Summary

Methods inherited from class com.azure.core.ServiceClient

Methods inherited from class java.lang.Object

Method Detail

builder

setSecret

setSecret

getSecret

getSecret

getSecret

updateSecret

deleteSecret

getDeletedSecret

purgeDeletedSecret

recoverDeletedSecret

backupSecret

restoreSecret

listSecrets

listDeletedSecrets

listSecretVersions