0
# Secret Management
1

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

4
## Core Operations
5

6
### Creating Secrets
7

8
#### CreateSecretRequest
9

10
```java { .api }
11
class CreateSecretRequest extends AmazonWebServiceRequest {
12
    String name;                              // Required: Secret name (unique within region)
13
    String secretString;                      // Secret value as string
14
    ByteBuffer secretBinary;                  // Secret value as binary data
15
    String description;                       // Human-readable description
16
    String kmsKeyId;                          // KMS key for encryption
17
    List<Tag> tags;                           // Resource tags
18
    List<ReplicaRegionType> addReplicaRegions; // Regions for replication
19
    Boolean forceOverwriteReplicaSecret;      // Force overwrite during replication
20
    String clientRequestToken;                // Idempotency token
21
}
22
```
23

24
#### CreateSecretResult
25

26
```java { .api }
27
class CreateSecretResult {
28
    String arn;                               // Secret ARN
29
    String name;                              // Secret name
30
    String versionId;                         // Initial version ID
31
    List<ReplicationStatusType> replicationStatus; // Replication status per region
32
}
33
```
34

35
#### Usage Example
36

37
```java { .api }
38
// Create a simple string secret
39
CreateSecretRequest request = new CreateSecretRequest()
40
    .withName("db/prod/password")
41
    .withSecretString("my-secure-password")
42
    .withDescription("Production database password");
43

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

47
// Create a JSON secret with tags
48
CreateSecretRequest jsonRequest = new CreateSecretRequest()
49
    .withName("api/credentials")
50
    .withSecretString("{\"username\":\"admin\",\"password\":\"secret123\"}")
51
    .withDescription("API credentials")
52
    .withTags(
53
        new Tag().withKey("Environment").withValue("Production"),
54
        new Tag().withKey("Team").withValue("Backend")
55
    );
56

57
CreateSecretResult jsonResult = client.createSecret(jsonRequest);
58
```
59

60
### Retrieving Secrets
61

62
#### GetSecretValueRequest
63

64
```java { .api }
65
class GetSecretValueRequest extends AmazonWebServiceRequest {
66
    String secretId;                          // Required: Secret name or ARN
67
    String versionId;                         // Specific version ID
68
    String versionStage;                      // Version stage (AWSCURRENT, AWSPENDING)
69
}
70
```
71

72
#### GetSecretValueResult
73

74
```java { .api }
75
class GetSecretValueResult {
76
    String arn;                               // Secret ARN
77
    String name;                              // Secret name
78
    String versionId;                         // Version ID retrieved
79
    ByteBuffer secretBinary;                  // Binary secret data
80
    String secretString;                      // String secret data
81
    List<String> versionStages;               // Version stages for this version
82
    Date createdDate;                         // Version creation date
83
}
84
```
85

86
#### Usage Example
87

88
```java { .api }
89
// Get current secret value
90
GetSecretValueRequest request = new GetSecretValueRequest()
91
    .withSecretId("db/prod/password");
92

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

96
// Get specific version
97
GetSecretValueRequest versionRequest = new GetSecretValueRequest()
98
    .withSecretId("api/credentials")
99
    .withVersionStage("AWSPENDING");
100

101
GetSecretValueResult versionResult = client.getSecretValue(versionRequest);
102

103
// Parse JSON secret
104
String jsonSecret = versionResult.getSecretString();
105
// Use a JSON parser to extract individual values
106
```
107

108
### Batch Retrieval
109

110
#### BatchGetSecretValueRequest
111

112
```java { .api }
113
class BatchGetSecretValueRequest extends AmazonWebServiceRequest {
114
    List<String> secretIdList;                // List of secret identifiers
115
    List<Filter> filters;                     // Filters to apply
116
    Integer maxResults;                       // Maximum results (1-20)
117
    String nextToken;                         // Pagination token
118
}
119
```
120

121
#### BatchGetSecretValueResult
122

123
```java { .api }
124
class BatchGetSecretValueResult {
125
    List<SecretValueEntry> secretValues;      // Retrieved secret values
126
    String nextToken;                         // Next pagination token
127
    List<APIErrorType> errors;                // Errors for failed retrievals
128
}
129
```
130

131
#### SecretValueEntry
132

133
```java { .api }
134
class SecretValueEntry {
135
    String arn;                               // Secret ARN
136
    String name;                              // Secret name
137
    String versionId;                         // Version ID
138
    ByteBuffer secretBinary;                  // Binary secret data
139
    String secretString;                      // String secret data
140
    List<String> versionStages;               // Version stages
141
    Date createdDate;                         // Creation date
142
}
143
```
144

145
#### Usage Example
146

147
```java { .api }
148
// Batch retrieve multiple secrets
149
BatchGetSecretValueRequest batchRequest = new BatchGetSecretValueRequest()
150
    .withSecretIdList(
151
        "db/prod/password",
152
        "api/credentials",
153
        "cache/redis/auth"
154
    );
155

156
BatchGetSecretValueResult batchResult = client.batchGetSecretValue(batchRequest);
157

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

163
// Handle errors
164
for (APIErrorType error : batchResult.getErrors()) {
165
    System.err.println("Failed to retrieve " + error.getSecretId() + 
166
                      ": " + error.getMessage());
167
}
168
```
169

170
### Updating Secrets
171

172
#### UpdateSecretRequest
173

174
```java { .api }
175
class UpdateSecretRequest extends AmazonWebServiceRequest {
176
    String secretId;                          // Required: Secret identifier
177
    String clientRequestToken;                // Idempotency token
178
    String description;                       // New description
179
    String kmsKeyId;                          // New KMS key
180
    ByteBuffer secretBinary;                  // New binary secret data
181
    String secretString;                      // New string secret data
182
}
183
```
184

185
#### UpdateSecretResult
186

187
```java { .api }
188
class UpdateSecretResult {
189
    String arn;                               // Secret ARN
190
    String name;                              // Secret name
191
    String versionId;                         // New version ID
192
}
193
```
194

195
#### PutSecretValueRequest
196

197
```java { .api }
198
class PutSecretValueRequest extends AmazonWebServiceRequest {
199
    String secretId;                          // Required: Secret identifier
200
    String clientRequestToken;                // Idempotency token
201
    ByteBuffer secretBinary;                  // Binary secret data
202
    String secretString;                      // String secret data
203
    List<String> versionStages;               // Version stages to apply
204
    String rotationToken;                     // Rotation token for automatic rotation
205
}
206
```
207

208
#### PutSecretValueResult
209

210
```java { .api }
211
class PutSecretValueResult {
212
    String arn;                               // Secret ARN
213
    String name;                              // Secret name
214
    String versionId;                         // New version ID
215
    List<String> versionStages;               // Applied version stages
216
}
217
```
218

219
#### Usage Example
220

221
```java { .api }
222
// Update secret metadata (description, KMS key)
223
UpdateSecretRequest updateRequest = new UpdateSecretRequest()
224
    .withSecretId("db/prod/password")
225
    .withDescription("Updated production database password")
226
    .withKmsKeyId("arn:aws:kms:us-west-2:123456789012:key/new-key-id");
227

228
UpdateSecretResult updateResult = client.updateSecret(updateRequest);
229

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

236
PutSecretValueResult putResult = client.putSecretValue(putRequest);
237
String newVersionId = putResult.getVersionId();
238
```
239

240
### Secret Metadata
241

242
#### DescribeSecretRequest
243

244
```java { .api }
245
class DescribeSecretRequest extends AmazonWebServiceRequest {
246
    String secretId;                          // Required: Secret identifier
247
}
248
```
249

250
#### DescribeSecretResult
251

252
```java { .api }
253
class DescribeSecretResult {
254
    String arn;                               // Secret ARN
255
    String name;                              // Secret name
256
    String description;                       // Secret description
257
    String kmsKeyId;                          // KMS key ID
258
    Boolean rotationEnabled;                  // Rotation enabled flag
259
    String rotationLambdaARN;                 // Rotation Lambda function ARN
260
    RotationRulesType rotationRules;          // Rotation configuration
261
    Date lastRotatedDate;                     // Last rotation timestamp
262
    Date lastChangedDate;                     // Last modification timestamp
263
    Date lastAccessedDate;                    // Last access timestamp (within 24 hours)
264
    Date deletionDate;                        // Scheduled deletion date
265
    List<Tag> tags;                           // Resource tags
266
    Map<String, List<String>> versionIdsToStages; // Version to stages mapping
267
    String owningService;                     // Service that owns the secret
268
    Date createdDate;                         // Creation timestamp
269
    String primaryRegion;                     // Primary region for multi-region secrets
270
    List<ReplicationStatusType> replicationStatus; // Replication status
271
    Date nextRotationDate;                    // Next scheduled rotation
272
}
273
```
274

275
#### Usage Example
276

277
```java { .api }
278
DescribeSecretRequest describeRequest = new DescribeSecretRequest()
279
    .withSecretId("db/prod/password");
280

281
DescribeSecretResult describeResult = client.describeSecret(describeRequest);
282

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

288
// Check version information
289
Map<String, List<String>> versions = describeResult.getVersionIdsToStages();
290
for (Map.Entry<String, List<String>> entry : versions.entrySet()) {
291
    System.out.println("Version " + entry.getKey() + 
292
                      " has stages: " + entry.getValue());
293
}
294
```
295

296
### Listing Secrets
297

298
#### ListSecretsRequest
299

300
```java { .api }
301
class ListSecretsRequest extends AmazonWebServiceRequest {
302
    Boolean includePlannedDeletion;           // Include secrets scheduled for deletion
303
    Integer maxResults;                       // Maximum results per page (1-100)
304
    String nextToken;                         // Pagination token
305
    List<Filter> filters;                     // Filters to apply
306
    SortOrderType sortOrder;                  // Sort order (asc/desc)
307
}
308
```
309

310
#### ListSecretsResult
311

312
```java { .api }
313
class ListSecretsResult {
314
    List<SecretListEntry> secretList;         // List of secrets
315
    String nextToken;                         // Next pagination token
316
}
317
```
318

319
#### SecretListEntry
320

321
```java { .api }
322
class SecretListEntry {
323
    String arn;                               // Secret ARN
324
    String name;                              // Secret name
325
    String description;                       // Secret description
326
    String kmsKeyId;                          // KMS key ID
327
    Boolean rotationEnabled;                  // Rotation enabled
328
    String rotationLambdaARN;                 // Rotation Lambda ARN
329
    RotationRulesType rotationRules;          // Rotation rules
330
    Date lastRotatedDate;                     // Last rotation date
331
    Date lastChangedDate;                     // Last change date
332
    Date lastAccessedDate;                    // Last access date
333
    Date deletionDate;                        // Deletion date
334
    List<Tag> tags;                           // Resource tags
335
    Map<String, List<String>> secretVersionsToStages; // Version stages
336
    String owningService;                     // Owning service
337
    Date createdDate;                         // Creation date
338
    String primaryRegion;                     // Primary region
339
    Date nextRotationDate;                    // Next rotation date
340
}
341
```
342

343
#### Filter
344

345
```java { .api }
346
class Filter {
347
    FilterNameStringType key;                 // Filter key type
348
    List<String> values;                      // Filter values
349
}
350

351
enum FilterNameStringType {
352
    Description,                              // Filter by description
353
    Name,                                     // Filter by name  
354
    Tag_key,                                  // Filter by tag key
355
    Tag_value,                                // Filter by tag value
356
    Primary_region,                           // Filter by primary region
357
    Owning_service,                           // Filter by owning service
358
    All                                       // All secrets
359
}
360
```
361

362
#### Usage Example
363

364
```java { .api }
365
// List all secrets with pagination
366
ListSecretsRequest listRequest = new ListSecretsRequest()
367
    .withMaxResults(50)
368
    .withSortOrder(SortOrderType.Asc);
369

370
ListSecretsResult listResult = client.listSecrets(listRequest);
371

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

377
// List with filters
378
List<Filter> filters = new ArrayList<>();
379
filters.add(new Filter()
380
    .withKey(FilterNameStringType.Tag_key)
381
    .withValues("Environment"));
382

383
ListSecretsRequest filteredRequest = new ListSecretsRequest()
384
    .withFilters(filters)
385
    .withIncludePlannedDeletion(false);
386

387
ListSecretsResult filteredResult = client.listSecrets(filteredRequest);
388
```
389

390
### Deleting Secrets
391

392
#### DeleteSecretRequest
393

394
```java { .api }
395
class DeleteSecretRequest extends AmazonWebServiceRequest {
396
    String secretId;                          // Required: Secret identifier
397
    Long recoveryWindowInDays;                // Recovery window (7-30 days)
398
    Boolean forceDeleteWithoutRecovery;       // Force immediate deletion
399
}
400
```
401

402
#### DeleteSecretResult
403

404
```java { .api }
405
class DeleteSecretResult {
406
    String arn;                               // Secret ARN
407
    String name;                              // Secret name
408
    Date deletionDate;                        // Scheduled deletion date
409
}
410
```
411

412
#### RestoreSecretRequest
413

414
```java { .api }
415
class RestoreSecretRequest extends AmazonWebServiceRequest {
416
    String secretId;                          // Required: Secret identifier
417
}
418
```
419

420
#### RestoreSecretResult
421

422
```java { .api }
423
class RestoreSecretResult {
424
    String arn;                               // Secret ARN
425
    String name;                              // Secret name
426
}
427
```
428

429
#### Usage Example
430

431
```java { .api }
432
// Schedule deletion with recovery window
433
DeleteSecretRequest deleteRequest = new DeleteSecretRequest()
434
    .withSecretId("old/api/key")
435
    .withRecoveryWindowInDays(30L);
436

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

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

446
client.deleteSecret(forceDeleteRequest);
447

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

452
RestoreSecretResult restoreResult = client.restoreSecret(restoreRequest);
453
System.out.println("Restored secret: " + restoreResult.getName());
454
```
455

456
### Version Management
457

458
#### ListSecretVersionIdsRequest
459

460
```java { .api }
461
class ListSecretVersionIdsRequest extends AmazonWebServiceRequest {
462
    String secretId;                          // Required: Secret identifier
463
    Integer maxResults;                       // Maximum results (1-100)
464
    String nextToken;                         // Pagination token
465
    Boolean includeDeprecated;                // Include deprecated versions
466
}
467
```
468

469
#### ListSecretVersionIdsResult
470

471
```java { .api }
472
class ListSecretVersionIdsResult {
473
    List<SecretVersionsListEntry> versions;   // Version entries
474
    String nextToken;                         // Next pagination token
475
    String arn;                               // Secret ARN
476
    String name;                              // Secret name
477
}
478
```
479

480
#### SecretVersionsListEntry
481

482
```java { .api }
483
class SecretVersionsListEntry {
484
    String versionId;                         // Version ID
485
    List<String> versionStages;               // Version stages
486
    Date lastAccessedDate;                    // Last access date
487
    Date createdDate;                         // Creation date
488
    List<String> kmsKeyIds;                   // KMS key IDs used
489
}
490
```
491

492
#### UpdateSecretVersionStageRequest
493

494
```java { .api }
495
class UpdateSecretVersionStageRequest extends AmazonWebServiceRequest {
496
    String secretId;                          // Required: Secret identifier
497
    String versionStage;                      // Required: Version stage to move
498
    String clientRequestToken;                // Idempotency token
499
    String moveToVersionId;                   // Version to move stage to
500
    String removeFromVersionId;               // Version to remove stage from
501
}
502
```
503

504
#### UpdateSecretVersionStageResult
505

506
```java { .api }
507
class UpdateSecretVersionStageResult {
508
    String arn;                               // Secret ARN
509
    String name;                              // Secret name
510
}
511
```
512

513
#### Usage Example
514

515
```java { .api }
516
// List all versions of a secret
517
ListSecretVersionIdsRequest versionRequest = new ListSecretVersionIdsRequest()
518
    .withSecretId("api/credentials")
519
    .withIncludeDeprecated(true);
520

521
ListSecretVersionIdsResult versionResult = client.listSecretVersionIds(versionRequest);
522

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

528
// Move AWSCURRENT stage to a different version
529
UpdateSecretVersionStageRequest stageRequest = new UpdateSecretVersionStageRequest()
530
    .withSecretId("api/credentials")
531
    .withVersionStage("AWSCURRENT")
532
    .withMoveToVersionId("v2-version-id")
533
    .withRemoveFromVersionId("v1-version-id");
534

535
UpdateSecretVersionStageResult stageResult = client.updateSecretVersionStage(stageRequest);
536
```
537

538
## Error Handling
539

540
Common exceptions for secret management operations:
541

542
```java { .api }
543
try {
544
    GetSecretValueResult result = client.getSecretValue(request);
545
} catch (ResourceNotFoundException e) {
546
    // Secret doesn't exist
547
    System.err.println("Secret not found: " + e.getMessage());
548
} catch (InvalidParameterException e) {
549
    // Invalid parameters provided
550
    System.err.println("Invalid parameter: " + e.getMessage());
551
} catch (DecryptionFailureException e) {
552
    // KMS decryption failed
553
    System.err.println("Decryption failed: " + e.getMessage());
554
} catch (LimitExceededException e) {
555
    // Service limits exceeded
556
    System.err.println("Limit exceeded: " + e.getMessage());
557
} catch (AWSSecretsManagerException e) {
558
    // Other service errors
559
    System.err.println("Service error: " + e.getMessage());
560
}
561
```