0
# AWS Secrets Manager Java SDK
1

2
A comprehensive Java SDK for AWS Secrets Manager service providing secure storage and management of sensitive information like database credentials, API keys, and other secrets.
3

4
## Package Information
5

6
```xml
7
<dependency>
8
    <groupId>com.amazonaws</groupId>
9
    <artifactId>aws-java-sdk-secretsmanager</artifactId>
10
    <version>1.12.789</version>
11
</dependency>
12
```
13

14
- **API Version:** 2017-10-17
15
- **Service Endpoint:** secretsmanager (regional)
16

17
## Core Imports
18

19
```java { .api }
20
// Core service interfaces
21
import com.amazonaws.services.secretsmanager.AWSSecretsManager;
22
import com.amazonaws.services.secretsmanager.AWSSecretsManagerAsync;
23

24
// Client implementations
25
import com.amazonaws.services.secretsmanager.AWSSecretsManagerClient;
26
import com.amazonaws.services.secretsmanager.AWSSecretsManagerAsyncClient;
27

28
// Client builders
29
import com.amazonaws.services.secretsmanager.AWSSecretsManagerClientBuilder;
30
import com.amazonaws.services.secretsmanager.AWSSecretsManagerAsyncClientBuilder;
31

32
// Common model classes
33
import com.amazonaws.services.secretsmanager.model.*;
34

35
// Exception handling
36
import com.amazonaws.services.secretsmanager.model.AWSSecretsManagerException;
37
import com.amazonaws.services.secretsmanager.model.ResourceNotFoundException;
38
import com.amazonaws.services.secretsmanager.model.InvalidParameterException;
39
```
40

41
## Basic Usage
42

43
### Creating a Client
44

45
```java { .api }
46
// Synchronous client with default configuration
47
AWSSecretsManager client = AWSSecretsManagerClientBuilder.defaultClient();
48

49
// Synchronous client with custom region
50
AWSSecretsManager client = AWSSecretsManagerClientBuilder.standard()
51
    .withRegion("us-west-2")
52
    .build();
53

54
// Asynchronous client
55
AWSSecretsManagerAsync asyncClient = AWSSecretsManagerAsyncClientBuilder.standard()
56
    .withRegion("us-west-2")
57
    .build();
58
```
59

60
### Simple Secret Operations
61

62
```java { .api }
63
// Create a secret
64
CreateSecretRequest createRequest = new CreateSecretRequest()
65
    .withName("MySecret")
66
    .withSecretString("my-secret-value")
67
    .withDescription("Database password for production");
68
CreateSecretResult createResult = client.createSecret(createRequest);
69

70
// Retrieve a secret value
71
GetSecretValueRequest getRequest = new GetSecretValueRequest()
72
    .withSecretId("MySecret");
73
GetSecretValueResult getResult = client.getSecretValue(getRequest);
74
String secretValue = getResult.getSecretString();
75

76
// Update secret value
77
UpdateSecretRequest updateRequest = new UpdateSecretRequest()
78
    .withSecretId("MySecret")
79
    .withSecretString("new-secret-value");
80
UpdateSecretResult updateResult = client.updateSecret(updateRequest);
81

82
// Delete a secret (with recovery window)
83
DeleteSecretRequest deleteRequest = new DeleteSecretRequest()
84
    .withSecretId("MySecret")
85
    .withRecoveryWindowInDays(30L);
86
DeleteSecretResult deleteResult = client.deleteSecret(deleteRequest);
87
```
88

89
## Core Service Interfaces
90

91
### AWSSecretsManager (Synchronous Interface)
92

93
```java { .api }
94
public interface AWSSecretsManager {
95
    // Service endpoint prefix
96
    String ENDPOINT_PREFIX = "secretsmanager";
97
    
98
    // Core secret operations
99
    CreateSecretResult createSecret(CreateSecretRequest request);
100
    GetSecretValueResult getSecretValue(GetSecretValueRequest request);
101
    UpdateSecretResult updateSecret(UpdateSecretRequest request);
102
    DeleteSecretResult deleteSecret(DeleteSecretRequest request);
103
    DescribeSecretResult describeSecret(DescribeSecretRequest request);
104
    ListSecretsResult listSecrets(ListSecretsRequest request);
105
    
106
    // Batch operations
107
    BatchGetSecretValueResult batchGetSecretValue(BatchGetSecretValueRequest request);
108
    
109
    // Secret value management
110
    PutSecretValueResult putSecretValue(PutSecretValueRequest request);
111
    
112
    // Version management
113
    ListSecretVersionIdsResult listSecretVersionIds(ListSecretVersionIdsRequest request);
114
    UpdateSecretVersionStageResult updateSecretVersionStage(UpdateSecretVersionStageRequest request);
115
    
116
    // Rotation operations
117
    RotateSecretResult rotateSecret(RotateSecretRequest request);
118
    CancelRotateSecretResult cancelRotateSecret(CancelRotateSecretRequest request);
119
    
120
    // Replication operations
121
    ReplicateSecretToRegionsResult replicateSecretToRegions(ReplicateSecretToRegionsRequest request);
122
    RemoveRegionsFromReplicationResult removeRegionsFromReplication(RemoveRegionsFromReplicationRequest request);
123
    StopReplicationToReplicaResult stopReplicationToReplica(StopReplicationToReplicaRequest request);
124
    RestoreSecretResult restoreSecret(RestoreSecretRequest request);
125
    
126
    // Resource policy operations
127
    GetResourcePolicyResult getResourcePolicy(GetResourcePolicyRequest request);
128
    PutResourcePolicyResult putResourcePolicy(PutResourcePolicyRequest request);
129
    DeleteResourcePolicyResult deleteResourcePolicy(DeleteResourcePolicyRequest request);
130
    ValidateResourcePolicyResult validateResourcePolicy(ValidateResourcePolicyRequest request);
131
    
132
    // Tagging operations
133
    TagResourceResult tagResource(TagResourceRequest request);
134
    UntagResourceResult untagResource(UntagResourceRequest request);
135
    
136
    // Utility operations
137
    GetRandomPasswordResult getRandomPassword(GetRandomPasswordRequest request);
138
    
139
    // Client lifecycle
140
    void shutdown();
141
    ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request);
142
}
143
```
144

145
### AWSSecretsManagerAsync (Asynchronous Interface)
146

147
```java { .api }
148
public interface AWSSecretsManagerAsync extends AWSSecretsManager {
149
    // All synchronous methods plus async variants
150
    
151
    // Batch operations
152
    Future<BatchGetSecretValueResult> batchGetSecretValueAsync(BatchGetSecretValueRequest request);
153
    Future<BatchGetSecretValueResult> batchGetSecretValueAsync(BatchGetSecretValueRequest request,
154
        AsyncHandler<BatchGetSecretValueRequest, BatchGetSecretValueResult> asyncHandler);
155
    
156
    // Rotation operations
157
    Future<CancelRotateSecretResult> cancelRotateSecretAsync(CancelRotateSecretRequest request);
158
    Future<CancelRotateSecretResult> cancelRotateSecretAsync(CancelRotateSecretRequest request,
159
        AsyncHandler<CancelRotateSecretRequest, CancelRotateSecretResult> asyncHandler);
160
    Future<RotateSecretResult> rotateSecretAsync(RotateSecretRequest request);
161
    Future<RotateSecretResult> rotateSecretAsync(RotateSecretRequest request,
162
        AsyncHandler<RotateSecretRequest, RotateSecretResult> asyncHandler);
163
    
164
    // Core secret operations
165
    Future<CreateSecretResult> createSecretAsync(CreateSecretRequest request);
166
    Future<CreateSecretResult> createSecretAsync(CreateSecretRequest request,
167
        AsyncHandler<CreateSecretRequest, CreateSecretResult> asyncHandler);
168
    Future<DeleteSecretResult> deleteSecretAsync(DeleteSecretRequest request);
169
    Future<DeleteSecretResult> deleteSecretAsync(DeleteSecretRequest request,
170
        AsyncHandler<DeleteSecretRequest, DeleteSecretResult> asyncHandler);
171
    Future<DescribeSecretResult> describeSecretAsync(DescribeSecretRequest request);
172
    Future<DescribeSecretResult> describeSecretAsync(DescribeSecretRequest request,
173
        AsyncHandler<DescribeSecretRequest, DescribeSecretResult> asyncHandler);
174
    Future<GetSecretValueResult> getSecretValueAsync(GetSecretValueRequest request);
175
    Future<GetSecretValueResult> getSecretValueAsync(GetSecretValueRequest request,
176
        AsyncHandler<GetSecretValueRequest, GetSecretValueResult> asyncHandler);
177
    Future<ListSecretsResult> listSecretsAsync(ListSecretsRequest request);
178
    Future<ListSecretsResult> listSecretsAsync(ListSecretsRequest request,
179
        AsyncHandler<ListSecretsRequest, ListSecretsResult> asyncHandler);
180
    Future<UpdateSecretResult> updateSecretAsync(UpdateSecretRequest request);
181
    Future<UpdateSecretResult> updateSecretAsync(UpdateSecretRequest request,
182
        AsyncHandler<UpdateSecretRequest, UpdateSecretResult> asyncHandler);
183
    
184
    // Secret value management
185
    Future<PutSecretValueResult> putSecretValueAsync(PutSecretValueRequest request);
186
    Future<PutSecretValueResult> putSecretValueAsync(PutSecretValueRequest request,
187
        AsyncHandler<PutSecretValueRequest, PutSecretValueResult> asyncHandler);
188
    
189
    // Version management
190
    Future<ListSecretVersionIdsResult> listSecretVersionIdsAsync(ListSecretVersionIdsRequest request);
191
    Future<ListSecretVersionIdsResult> listSecretVersionIdsAsync(ListSecretVersionIdsRequest request,
192
        AsyncHandler<ListSecretVersionIdsRequest, ListSecretVersionIdsResult> asyncHandler);
193
    Future<UpdateSecretVersionStageResult> updateSecretVersionStageAsync(UpdateSecretVersionStageRequest request);
194
    Future<UpdateSecretVersionStageResult> updateSecretVersionStageAsync(UpdateSecretVersionStageRequest request,
195
        AsyncHandler<UpdateSecretVersionStageRequest, UpdateSecretVersionStageResult> asyncHandler);
196
    
197
    // Replication operations
198
    Future<ReplicateSecretToRegionsResult> replicateSecretToRegionsAsync(ReplicateSecretToRegionsRequest request);
199
    Future<ReplicateSecretToRegionsResult> replicateSecretToRegionsAsync(ReplicateSecretToRegionsRequest request,
200
        AsyncHandler<ReplicateSecretToRegionsRequest, ReplicateSecretToRegionsResult> asyncHandler);
201
    Future<RemoveRegionsFromReplicationResult> removeRegionsFromReplicationAsync(RemoveRegionsFromReplicationRequest request);
202
    Future<RemoveRegionsFromReplicationResult> removeRegionsFromReplicationAsync(RemoveRegionsFromReplicationRequest request,
203
        AsyncHandler<RemoveRegionsFromReplicationRequest, RemoveRegionsFromReplicationResult> asyncHandler);
204
    Future<StopReplicationToReplicaResult> stopReplicationToReplicaAsync(StopReplicationToReplicaRequest request);
205
    Future<StopReplicationToReplicaResult> stopReplicationToReplicaAsync(StopReplicationToReplicaRequest request,
206
        AsyncHandler<StopReplicationToReplicaRequest, StopReplicationToReplicaResult> asyncHandler);
207
    Future<RestoreSecretResult> restoreSecretAsync(RestoreSecretRequest request);
208
    Future<RestoreSecretResult> restoreSecretAsync(RestoreSecretRequest request,
209
        AsyncHandler<RestoreSecretRequest, RestoreSecretResult> asyncHandler);
210
    
211
    // Resource policy operations
212
    Future<GetResourcePolicyResult> getResourcePolicyAsync(GetResourcePolicyRequest request);
213
    Future<GetResourcePolicyResult> getResourcePolicyAsync(GetResourcePolicyRequest request,
214
        AsyncHandler<GetResourcePolicyRequest, GetResourcePolicyResult> asyncHandler);
215
    Future<PutResourcePolicyResult> putResourcePolicyAsync(PutResourcePolicyRequest request);
216
    Future<PutResourcePolicyResult> putResourcePolicyAsync(PutResourcePolicyRequest request,
217
        AsyncHandler<PutResourcePolicyRequest, PutResourcePolicyResult> asyncHandler);
218
    Future<DeleteResourcePolicyResult> deleteResourcePolicyAsync(DeleteResourcePolicyRequest request);
219
    Future<DeleteResourcePolicyResult> deleteResourcePolicyAsync(DeleteResourcePolicyRequest request,
220
        AsyncHandler<DeleteResourcePolicyRequest, DeleteResourcePolicyResult> asyncHandler);
221
    Future<ValidateResourcePolicyResult> validateResourcePolicyAsync(ValidateResourcePolicyRequest request);
222
    Future<ValidateResourcePolicyResult> validateResourcePolicyAsync(ValidateResourcePolicyRequest request,
223
        AsyncHandler<ValidateResourcePolicyRequest, ValidateResourcePolicyResult> asyncHandler);
224
    
225
    // Tagging operations
226
    Future<TagResourceResult> tagResourceAsync(TagResourceRequest request);
227
    Future<TagResourceResult> tagResourceAsync(TagResourceRequest request,
228
        AsyncHandler<TagResourceRequest, TagResourceResult> asyncHandler);
229
    Future<UntagResourceResult> untagResourceAsync(UntagResourceRequest request);
230
    Future<UntagResourceResult> untagResourceAsync(UntagResourceRequest request,
231
        AsyncHandler<UntagResourceRequest, UntagResourceResult> asyncHandler);
232
    
233
    // Utility operations
234
    Future<GetRandomPasswordResult> getRandomPasswordAsync(GetRandomPasswordRequest request);
235
    Future<GetRandomPasswordResult> getRandomPasswordAsync(GetRandomPasswordRequest request,
236
        AsyncHandler<GetRandomPasswordRequest, GetRandomPasswordResult> asyncHandler);
237
}
238
```
239

240
## Architecture
241

242
The AWS Secrets Manager Java SDK follows standard AWS SDK patterns:
243

244
1. **Service Interfaces**: Define the contract for operations (`AWSSecretsManager`, `AWSSecretsManagerAsync`)
245
2. **Client Implementations**: Provide concrete implementations (`AWSSecretsManagerClient`, `AWSSecretsManagerAsyncClient`)
246
3. **Builders**: Configure and create client instances (`AWSSecretsManagerClientBuilder`)
247
4. **Request/Response Models**: Strongly-typed objects for all API operations
248
5. **Exception Hierarchy**: Structured exception handling for different error conditions
249

250
## Capabilities
251

252
The AWS Secrets Manager SDK provides comprehensive functionality organized into key areas:
253

254
### [Secret Management](./secret-management.md)
255
Core CRUD operations for secrets including creation, retrieval, updates, deletion, and lifecycle management. Covers both individual and batch operations.
256

257
### [Rotation Management](./rotation.md)
258
Automated secret rotation capabilities including rotation configuration, execution, cancellation, and version stage management for seamless credential updates.
259

260
### [Replication Management](./replication.md)
261
Multi-region secret replication for high availability and disaster recovery, including cross-region setup, management, and cleanup operations.
262

263
### [Policies and Tagging](./policies-tags.md)
264
Resource-based access control through IAM policies and organizational management through resource tagging for governance and cost allocation.
265

266
### [Utility Operations](./utilities.md)
267
Helper functions including secure random password generation and resource policy validation for enhanced security and compliance.
268

269
## Exception Handling
270

271
All operations can throw AWS Secrets Manager specific exceptions:
272

273
```java { .api }
274
// Base exception class
275
class AWSSecretsManagerException extends AmazonServiceException {
276
    // Inherits standard AWS error information
277
}
278

279
// Resource-related exceptions
280
class ResourceNotFoundException extends AWSSecretsManagerException {}
281
class ResourceExistsException extends AWSSecretsManagerException {}
282

283
// Parameter and request validation exceptions
284
class InvalidParameterException extends AWSSecretsManagerException {}
285
class InvalidRequestException extends AWSSecretsManagerException {}
286
class InvalidNextTokenException extends AWSSecretsManagerException {}
287

288
// Encryption and security exceptions
289
class DecryptionFailureException extends AWSSecretsManagerException {}
290
class EncryptionFailureException extends AWSSecretsManagerException {}
291

292
// Policy-related exceptions
293
class MalformedPolicyDocumentException extends AWSSecretsManagerException {}
294
class PublicPolicyException extends AWSSecretsManagerException {}
295

296
// Quota and precondition exceptions
297
class LimitExceededException extends AWSSecretsManagerException {}
298
class PreconditionNotMetException extends AWSSecretsManagerException {}
299

300
// Service availability exception
301
class InternalServiceErrorException extends AWSSecretsManagerException {}
302
```
303

304
## Best Practices
305

306
1. **Client Management**: Use client builders and reuse client instances across operations
307
2. **Error Handling**: Implement proper exception handling for all service operations
308
3. **Security**: Use IAM roles and policies to control access to secrets
309
4. **Pagination**: Handle pagination for list operations using nextToken
310
5. **Resource Cleanup**: Call `shutdown()` on clients when done to release resources
311
6. **Async Operations**: Use async clients for high-throughput scenarios
312

313
## Thread Safety
314

315
- Client instances are thread-safe and can be shared across multiple threads
316
- Request and response objects are not thread-safe
317
- Async handlers should be designed for concurrent execution