CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-amazonaws--aws-java-sdk-secretsmanager

Java client library for AWS Secrets Manager enabling secure storage, management, and retrieval of secrets.

—

Pending
Overview
Eval results
Files

secret-management.mddocs/

Secret Management

Core CRUD operations for managing secrets in AWS Secrets Manager, including creation, retrieval, updates, deletion, and lifecycle management.

Core Operations

Creating Secrets

CreateSecretRequest

class CreateSecretRequest extends AmazonWebServiceRequest {
    String name;                              // Required: Secret name (unique within region)
    String secretString;                      // Secret value as string
    ByteBuffer secretBinary;                  // Secret value as binary data
    String description;                       // Human-readable description
    String kmsKeyId;                          // KMS key for encryption
    List<Tag> tags;                           // Resource tags
    List<ReplicaRegionType> addReplicaRegions; // Regions for replication
    Boolean forceOverwriteReplicaSecret;      // Force overwrite during replication
    String clientRequestToken;                // Idempotency token
}

CreateSecretResult

class CreateSecretResult {
    String arn;                               // Secret ARN
    String name;                              // Secret name
    String versionId;                         // Initial version ID
    List<ReplicationStatusType> replicationStatus; // Replication status per region
}

Usage Example

// Create a simple string secret
CreateSecretRequest request = new CreateSecretRequest()
    .withName("db/prod/password")
    .withSecretString("my-secure-password")
    .withDescription("Production database password");

CreateSecretResult result = client.createSecret(request);
String secretArn = result.getArn();

// Create a JSON secret with tags
CreateSecretRequest jsonRequest = new CreateSecretRequest()
    .withName("api/credentials")
    .withSecretString("{\"username\":\"admin\",\"password\":\"secret123\"}")
    .withDescription("API credentials")
    .withTags(
        new Tag().withKey("Environment").withValue("Production"),
        new Tag().withKey("Team").withValue("Backend")
    );

CreateSecretResult jsonResult = client.createSecret(jsonRequest);

Retrieving Secrets

GetSecretValueRequest

class GetSecretValueRequest extends AmazonWebServiceRequest {
    String secretId;                          // Required: Secret name or ARN
    String versionId;                         // Specific version ID
    String versionStage;                      // Version stage (AWSCURRENT, AWSPENDING)
}

GetSecretValueResult

class GetSecretValueResult {
    String arn;                               // Secret ARN
    String name;                              // Secret name
    String versionId;                         // Version ID retrieved
    ByteBuffer secretBinary;                  // Binary secret data
    String secretString;                      // String secret data
    List<String> versionStages;               // Version stages for this version
    Date createdDate;                         // Version creation date
}

Usage Example

// Get current secret value
GetSecretValueRequest request = new GetSecretValueRequest()
    .withSecretId("db/prod/password");

GetSecretValueResult result = client.getSecretValue(request);
String secretValue = result.getSecretString();

// Get specific version
GetSecretValueRequest versionRequest = new GetSecretValueRequest()
    .withSecretId("api/credentials")
    .withVersionStage("AWSPENDING");

GetSecretValueResult versionResult = client.getSecretValue(versionRequest);

// Parse JSON secret
String jsonSecret = versionResult.getSecretString();
// Use a JSON parser to extract individual values

Batch Retrieval

BatchGetSecretValueRequest

class BatchGetSecretValueRequest extends AmazonWebServiceRequest {
    List<String> secretIdList;                // List of secret identifiers
    List<Filter> filters;                     // Filters to apply
    Integer maxResults;                       // Maximum results (1-20)
    String nextToken;                         // Pagination token
}

BatchGetSecretValueResult

class BatchGetSecretValueResult {
    List<SecretValueEntry> secretValues;      // Retrieved secret values
    String nextToken;                         // Next pagination token
    List<APIErrorType> errors;                // Errors for failed retrievals
}

SecretValueEntry

class SecretValueEntry {
    String arn;                               // Secret ARN
    String name;                              // Secret name
    String versionId;                         // Version ID
    ByteBuffer secretBinary;                  // Binary secret data
    String secretString;                      // String secret data
    List<String> versionStages;               // Version stages
    Date createdDate;                         // Creation date
}

Usage Example

// Batch retrieve multiple secrets
BatchGetSecretValueRequest batchRequest = new BatchGetSecretValueRequest()
    .withSecretIdList(
        "db/prod/password",
        "api/credentials",
        "cache/redis/auth"
    );

BatchGetSecretValueResult batchResult = client.batchGetSecretValue(batchRequest);

for (SecretValueEntry entry : batchResult.getSecretValues()) {
    System.out.println("Secret: " + entry.getName() + 
                      " Value: " + entry.getSecretString());
}

// Handle errors
for (APIErrorType error : batchResult.getErrors()) {
    System.err.println("Failed to retrieve " + error.getSecretId() + 
                      ": " + error.getMessage());
}

Updating Secrets

UpdateSecretRequest

class UpdateSecretRequest extends AmazonWebServiceRequest {
    String secretId;                          // Required: Secret identifier
    String clientRequestToken;                // Idempotency token
    String description;                       // New description
    String kmsKeyId;                          // New KMS key
    ByteBuffer secretBinary;                  // New binary secret data
    String secretString;                      // New string secret data
}

UpdateSecretResult

class UpdateSecretResult {
    String arn;                               // Secret ARN
    String name;                              // Secret name
    String versionId;                         // New version ID
}

PutSecretValueRequest

class PutSecretValueRequest extends AmazonWebServiceRequest {
    String secretId;                          // Required: Secret identifier
    String clientRequestToken;                // Idempotency token
    ByteBuffer secretBinary;                  // Binary secret data
    String secretString;                      // String secret data
    List<String> versionStages;               // Version stages to apply
    String rotationToken;                     // Rotation token for automatic rotation
}

PutSecretValueResult

class PutSecretValueResult {
    String arn;                               // Secret ARN
    String name;                              // Secret name
    String versionId;                         // New version ID
    List<String> versionStages;               // Applied version stages
}

Usage Example

// Update secret metadata (description, KMS key)
UpdateSecretRequest updateRequest = new UpdateSecretRequest()
    .withSecretId("db/prod/password")
    .withDescription("Updated production database password")
    .withKmsKeyId("arn:aws:kms:us-west-2:123456789012:key/new-key-id");

UpdateSecretResult updateResult = client.updateSecret(updateRequest);

// Update secret value (creates new version)
PutSecretValueRequest putRequest = new PutSecretValueRequest()
    .withSecretId("api/credentials")
    .withSecretString("{\"username\":\"admin\",\"password\":\"newPassword123\"}")
    .withVersionStages("AWSCURRENT");

PutSecretValueResult putResult = client.putSecretValue(putRequest);
String newVersionId = putResult.getVersionId();

Secret Metadata

DescribeSecretRequest

class DescribeSecretRequest extends AmazonWebServiceRequest {
    String secretId;                          // Required: Secret identifier
}

DescribeSecretResult

class DescribeSecretResult {
    String arn;                               // Secret ARN
    String name;                              // Secret name
    String description;                       // Secret description
    String kmsKeyId;                          // KMS key ID
    Boolean rotationEnabled;                  // Rotation enabled flag
    String rotationLambdaARN;                 // Rotation Lambda function ARN
    RotationRulesType rotationRules;          // Rotation configuration
    Date lastRotatedDate;                     // Last rotation timestamp
    Date lastChangedDate;                     // Last modification timestamp
    Date lastAccessedDate;                    // Last access timestamp (within 24 hours)
    Date deletionDate;                        // Scheduled deletion date
    List<Tag> tags;                           // Resource tags
    Map<String, List<String>> versionIdsToStages; // Version to stages mapping
    String owningService;                     // Service that owns the secret
    Date createdDate;                         // Creation timestamp
    String primaryRegion;                     // Primary region for multi-region secrets
    List<ReplicationStatusType> replicationStatus; // Replication status
    Date nextRotationDate;                    // Next scheduled rotation
}

Usage Example

DescribeSecretRequest describeRequest = new DescribeSecretRequest()
    .withSecretId("db/prod/password");

DescribeSecretResult describeResult = client.describeSecret(describeRequest);

System.out.println("Secret Name: " + describeResult.getName());
System.out.println("Description: " + describeResult.getDescription());
System.out.println("Rotation Enabled: " + describeResult.getRotationEnabled());
System.out.println("Last Changed: " + describeResult.getLastChangedDate());

// Check version information
Map<String, List<String>> versions = describeResult.getVersionIdsToStages();
for (Map.Entry<String, List<String>> entry : versions.entrySet()) {
    System.out.println("Version " + entry.getKey() + 
                      " has stages: " + entry.getValue());
}

Listing Secrets

ListSecretsRequest

class ListSecretsRequest extends AmazonWebServiceRequest {
    Boolean includePlannedDeletion;           // Include secrets scheduled for deletion
    Integer maxResults;                       // Maximum results per page (1-100)
    String nextToken;                         // Pagination token
    List<Filter> filters;                     // Filters to apply
    SortOrderType sortOrder;                  // Sort order (asc/desc)
}

ListSecretsResult

class ListSecretsResult {
    List<SecretListEntry> secretList;         // List of secrets
    String nextToken;                         // Next pagination token
}

SecretListEntry

class SecretListEntry {
    String arn;                               // Secret ARN
    String name;                              // Secret name
    String description;                       // Secret description
    String kmsKeyId;                          // KMS key ID
    Boolean rotationEnabled;                  // Rotation enabled
    String rotationLambdaARN;                 // Rotation Lambda ARN
    RotationRulesType rotationRules;          // Rotation rules
    Date lastRotatedDate;                     // Last rotation date
    Date lastChangedDate;                     // Last change date
    Date lastAccessedDate;                    // Last access date
    Date deletionDate;                        // Deletion date
    List<Tag> tags;                           // Resource tags
    Map<String, List<String>> secretVersionsToStages; // Version stages
    String owningService;                     // Owning service
    Date createdDate;                         // Creation date
    String primaryRegion;                     // Primary region
    Date nextRotationDate;                    // Next rotation date
}

Filter

class Filter {
    FilterNameStringType key;                 // Filter key type
    List<String> values;                      // Filter values
}

enum FilterNameStringType {
    Description,                              // Filter by description
    Name,                                     // Filter by name  
    Tag_key,                                  // Filter by tag key
    Tag_value,                                // Filter by tag value
    Primary_region,                           // Filter by primary region
    Owning_service,                           // Filter by owning service
    All                                       // All secrets
}

Usage Example

// List all secrets with pagination
ListSecretsRequest listRequest = new ListSecretsRequest()
    .withMaxResults(50)
    .withSortOrder(SortOrderType.Asc);

ListSecretsResult listResult = client.listSecrets(listRequest);

for (SecretListEntry secret : listResult.getSecretList()) {
    System.out.println("Secret: " + secret.getName() + 
                      " - " + secret.getDescription());
}

// List with filters
List<Filter> filters = new ArrayList<>();
filters.add(new Filter()
    .withKey(FilterNameStringType.Tag_key)
    .withValues("Environment"));

ListSecretsRequest filteredRequest = new ListSecretsRequest()
    .withFilters(filters)
    .withIncludePlannedDeletion(false);

ListSecretsResult filteredResult = client.listSecrets(filteredRequest);

Deleting Secrets

DeleteSecretRequest

class DeleteSecretRequest extends AmazonWebServiceRequest {
    String secretId;                          // Required: Secret identifier
    Long recoveryWindowInDays;                // Recovery window (7-30 days)
    Boolean forceDeleteWithoutRecovery;       // Force immediate deletion
}

DeleteSecretResult

class DeleteSecretResult {
    String arn;                               // Secret ARN
    String name;                              // Secret name
    Date deletionDate;                        // Scheduled deletion date
}

RestoreSecretRequest

class RestoreSecretRequest extends AmazonWebServiceRequest {
    String secretId;                          // Required: Secret identifier
}

RestoreSecretResult

class RestoreSecretResult {
    String arn;                               // Secret ARN
    String name;                              // Secret name
}

Usage Example

// Schedule deletion with recovery window
DeleteSecretRequest deleteRequest = new DeleteSecretRequest()
    .withSecretId("old/api/key")
    .withRecoveryWindowInDays(30L);

DeleteSecretResult deleteResult = client.deleteSecret(deleteRequest);
System.out.println("Secret scheduled for deletion on: " + 
                  deleteResult.getDeletionDate());

// Force immediate deletion (no recovery)
DeleteSecretRequest forceDeleteRequest = new DeleteSecretRequest()
    .withSecretId("temp/secret")
    .withForceDeleteWithoutRecovery(true);

client.deleteSecret(forceDeleteRequest);

// Restore a scheduled deletion
RestoreSecretRequest restoreRequest = new RestoreSecretRequest()
    .withSecretId("old/api/key");

RestoreSecretResult restoreResult = client.restoreSecret(restoreRequest);
System.out.println("Restored secret: " + restoreResult.getName());

Version Management

ListSecretVersionIdsRequest

class ListSecretVersionIdsRequest extends AmazonWebServiceRequest {
    String secretId;                          // Required: Secret identifier
    Integer maxResults;                       // Maximum results (1-100)
    String nextToken;                         // Pagination token
    Boolean includeDeprecated;                // Include deprecated versions
}

ListSecretVersionIdsResult

class ListSecretVersionIdsResult {
    List<SecretVersionsListEntry> versions;   // Version entries
    String nextToken;                         // Next pagination token
    String arn;                               // Secret ARN
    String name;                              // Secret name
}

SecretVersionsListEntry

class SecretVersionsListEntry {
    String versionId;                         // Version ID
    List<String> versionStages;               // Version stages
    Date lastAccessedDate;                    // Last access date
    Date createdDate;                         // Creation date
    List<String> kmsKeyIds;                   // KMS key IDs used
}

UpdateSecretVersionStageRequest

class UpdateSecretVersionStageRequest extends AmazonWebServiceRequest {
    String secretId;                          // Required: Secret identifier
    String versionStage;                      // Required: Version stage to move
    String clientRequestToken;                // Idempotency token
    String moveToVersionId;                   // Version to move stage to
    String removeFromVersionId;               // Version to remove stage from
}

UpdateSecretVersionStageResult

class UpdateSecretVersionStageResult {
    String arn;                               // Secret ARN
    String name;                              // Secret name
}

Usage Example

// List all versions of a secret
ListSecretVersionIdsRequest versionRequest = new ListSecretVersionIdsRequest()
    .withSecretId("api/credentials")
    .withIncludeDeprecated(true);

ListSecretVersionIdsResult versionResult = client.listSecretVersionIds(versionRequest);

for (SecretVersionsListEntry version : versionResult.getVersions()) {
    System.out.println("Version: " + version.getVersionId() + 
                      " Stages: " + version.getVersionStages());
}

// Move AWSCURRENT stage to a different version
UpdateSecretVersionStageRequest stageRequest = new UpdateSecretVersionStageRequest()
    .withSecretId("api/credentials")
    .withVersionStage("AWSCURRENT")
    .withMoveToVersionId("v2-version-id")
    .withRemoveFromVersionId("v1-version-id");

UpdateSecretVersionStageResult stageResult = client.updateSecretVersionStage(stageRequest);

Error Handling

Common exceptions for secret management operations:

try {
    GetSecretValueResult result = client.getSecretValue(request);
} catch (ResourceNotFoundException e) {
    // Secret doesn't exist
    System.err.println("Secret not found: " + e.getMessage());
} catch (InvalidParameterException e) {
    // Invalid parameters provided
    System.err.println("Invalid parameter: " + e.getMessage());
} catch (DecryptionFailureException e) {
    // KMS decryption failed
    System.err.println("Decryption failed: " + e.getMessage());
} catch (LimitExceededException e) {
    // Service limits exceeded
    System.err.println("Limit exceeded: " + e.getMessage());
} catch (AWSSecretsManagerException e) {
    // Other service errors
    System.err.println("Service error: " + e.getMessage());
}

Install with Tessl CLI

npx tessl i tessl/maven-com-amazonaws--aws-java-sdk-secretsmanager

docs

index.md

policies-tags.md

replication.md

rotation.md

secret-management.md

utilities.md

tile.json