# PutSecretValue


Creates a new version of your secret by creating a new encrypted value and attaching it to the secret. version can contain a new `SecretString` value or a new `SecretBinary` value. 

Do not call `PutSecretValue` at a sustained rate of more than once every 10 minutes. When you update the secret value, Secrets Manager creates a new version of the secret. Secrets Manager keeps 100 of the most recent versions, but it keeps *all* secret versions created in the last 24 hours. If you call `PutSecretValue` more than once every 10 minutes, you will create more versions than Secrets Manager removes, and you will reach the quota for secret versions.

You can specify the staging labels to attach to the new version in `VersionStages`. If you don't include `VersionStages`, then Secrets Manager automatically moves the staging label `AWSCURRENT` to this version. If this operation creates the first version for the secret, then Secrets Manager automatically attaches the staging label `AWSCURRENT` to it. If this operation moves the staging label `AWSCURRENT` from another version to this version, then Secrets Manager also automatically moves the staging label `AWSPREVIOUS` to the version that `AWSCURRENT` was removed from.

This operation is idempotent. If you call this operation with a `ClientRequestToken` that matches an existing version's VersionId, and you specify the same secret data, the operation succeeds but does nothing. However, if the secret data is different, then the operation fails because you can't modify an existing version; you can only create new ones.

Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters except `SecretBinary`, `SecretString`, or `RotationToken` because it might be logged. For more information, see [Logging Secrets Manager events with AWS CloudTrail](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieve-ct-entries.html).

 **Required permissions: ** `secretsmanager:PutSecretValue`. For more information, see [ IAM policy actions for Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions) and [Authentication and access control in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html). 

**Important**  
When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. This is a concern if the command includes the value of a secret. Learn how to [Mitigate the risks of using command-line tools to store AWS Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security_cli-exposure-risks.html).

## Request Syntax


```
{
   "ClientRequestToken": "string",
   "RotationToken": "string",
   "SecretBinary": blob,
   "SecretId": "string",
   "SecretString": "string",
   "VersionStages": [ "string" ]
}
```

## Request Parameters


For information about the parameters that are common to all actions, see [Common Parameters](CommonParameters.md).

The request accepts the following data in JSON format.

 ** [ClientRequestToken](#API_PutSecretValue_RequestSyntax) **   <a name="SecretsManager-PutSecretValue-request-ClientRequestToken"></a>
A unique identifier for the new version of the secret.   
If you use the AWS CLI or one of the AWS SDKs to call this operation, then you can leave this parameter empty. The CLI or SDK generates a random UUID for you and includes it as the value for this parameter in the request. 
If you generate a raw HTTP request to the Secrets Manager service endpoint, then you must generate a `ClientRequestToken` and include it in the request.  
This value helps ensure idempotency. Secrets Manager uses this value to prevent the accidental creation of duplicate versions if there are failures and retries during a rotation. We recommend that you generate a [UUID-type](https://wikipedia.org/wiki/Universally_unique_identifier) value to ensure uniqueness of your versions within the specified secret.   
+ If the `ClientRequestToken` value isn't already associated with a version of the secret then a new version of the secret is created. 
+ If a version with this value already exists and that version's `SecretString` or `SecretBinary` values are the same as those in the request then the request is ignored. The operation is idempotent. 
+ If a version with this value already exists and the version of the `SecretString` and `SecretBinary` values are different from those in the request, then the request fails because you can't modify a secret version. You can only create new versions to store new secret values.
This value becomes the `VersionId` of the new version.  
Type: String  
Length Constraints: Minimum length of 32. Maximum length of 64.  
Required: No

 ** [RotationToken](#API_PutSecretValue_RequestSyntax) **   <a name="SecretsManager-PutSecretValue-request-RotationToken"></a>
A unique identifier that indicates the source of the request. Required for secret rotations using an IAM assumed role or cross-account rotation, in which you rotate a secret in one account by using a Lambda rotation function in another account. In both cases, the rotation function assumes an IAM role to call Secrets Manager, and then Secrets Manager validates the identity using the token. For more information, see [How rotation works](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) and [Rotation by Lambda functions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotate-secrets_lambda).  
Sensitive: This field contains sensitive information, so the service does not include it in AWS CloudTrail log entries. If you create your own log entries, you must also avoid logging the information in this field.  
Type: String  
Length Constraints: Minimum length of 36. Maximum length of 256.  
Pattern: `^[a-zA-Z0-9\-]+$`   
Required: No

 ** [SecretBinary](#API_PutSecretValue_RequestSyntax) **   <a name="SecretsManager-PutSecretValue-request-SecretBinary"></a>
The binary data to encrypt and store in the new version of the secret. To use this parameter in the command-line tools, we recommend that you store your binary data in a file and then pass the contents of the file as a parameter.   
You must include `SecretBinary` or `SecretString`, but not both.  
You can't access this value from the Secrets Manager console.  
Sensitive: This field contains sensitive information, so the service does not include it in AWS CloudTrail log entries. If you create your own log entries, you must also avoid logging the information in this field.  
Type: Base64-encoded binary data object  
Length Constraints: Minimum length of 1. Maximum length of 65536.  
Required: No

 ** [SecretId](#API_PutSecretValue_RequestSyntax) **   <a name="SecretsManager-PutSecretValue-request-SecretId"></a>
The ARN or name of the secret to add a new version to.  
For an ARN, we recommend that you specify a complete ARN rather than a partial ARN. See [Finding a secret from a partial ARN](https://docs.aws.amazon.com/secretsmanager/latest/userguide/troubleshoot.html#ARN_secretnamehyphen).  
If the secret doesn't already exist, use `CreateSecret` instead.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 2048.  
Required: Yes

 ** [SecretString](#API_PutSecretValue_RequestSyntax) **   <a name="SecretsManager-PutSecretValue-request-SecretString"></a>
The text to encrypt and store in the new version of the secret.   
You must include `SecretBinary` or `SecretString`, but not both.  
We recommend you create the secret string as JSON key/value pairs, as shown in the example.  
Sensitive: This field contains sensitive information, so the service does not include it in AWS CloudTrail log entries. If you create your own log entries, you must also avoid logging the information in this field.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 65536.  
Required: No

 ** [VersionStages](#API_PutSecretValue_RequestSyntax) **   <a name="SecretsManager-PutSecretValue-request-VersionStages"></a>
A list of staging labels to attach to this version of the secret. Secrets Manager uses staging labels to track versions of a secret through the rotation process.  
If you specify a staging label that's already associated with a different version of the same secret, then Secrets Manager removes the label from the other version and attaches it to this version. If you specify `AWSCURRENT`, and it is already attached to another version, then Secrets Manager also moves the staging label `AWSPREVIOUS` to the version that `AWSCURRENT` was removed from.  
If you don't include `VersionStages`, then Secrets Manager automatically moves the staging label `AWSCURRENT` to this version.  
Type: Array of strings  
Array Members: Minimum number of 1 item. Maximum number of 20 items.  
Length Constraints: Minimum length of 1. Maximum length of 256.  
Required: No

## Response Syntax


```
{
   "ARN": "string",
   "Name": "string",
   "VersionId": "string",
   "VersionStages": [ "string" ]
}
```

## Response Elements


If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

 ** [ARN](#API_PutSecretValue_ResponseSyntax) **   <a name="SecretsManager-PutSecretValue-response-ARN"></a>
The ARN of the secret.  
Type: String  
Length Constraints: Minimum length of 20. Maximum length of 2048.

 ** [Name](#API_PutSecretValue_ResponseSyntax) **   <a name="SecretsManager-PutSecretValue-response-Name"></a>
The name of the secret.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 256.

 ** [VersionId](#API_PutSecretValue_ResponseSyntax) **   <a name="SecretsManager-PutSecretValue-response-VersionId"></a>
The unique identifier of the version of the secret.  
Type: String  
Length Constraints: Minimum length of 32. Maximum length of 64.

 ** [VersionStages](#API_PutSecretValue_ResponseSyntax) **   <a name="SecretsManager-PutSecretValue-response-VersionStages"></a>
The list of staging labels that are currently attached to this version of the secret. Secrets Manager uses staging labels to track a version as it progresses through the secret rotation process.  
Type: Array of strings  
Array Members: Minimum number of 1 item. Maximum number of 20 items.  
Length Constraints: Minimum length of 1. Maximum length of 256.

## Errors


For information about the errors that are common to all actions, see [Common Errors](CommonErrors.md).

 ** DecryptionFailure **   
Secrets Manager can't decrypt the protected secret text using the provided KMS key.   
HTTP Status Code: 400

 ** EncryptionFailure **   
Secrets Manager can't encrypt the protected secret text using the provided KMS key. Check that the KMS key is available, enabled, and not in an invalid state. For more information, see [Key state: Effect on your KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html).  
HTTP Status Code: 400

 ** InternalServiceError **   
An error occurred on the server side.  
HTTP Status Code: 500

 ** InvalidParameterException **   
The parameter name or value is invalid.  
HTTP Status Code: 400

 ** InvalidRequestException **   
A parameter value is not valid for the current state of the resource.  
Possible causes:  
+ The secret is scheduled for deletion.
+ You tried to enable rotation on a secret that doesn't already have a Lambda function ARN configured and you didn't include such an ARN as a parameter in this call. 
+ The secret is managed by another service, and you must use that service to update it. For more information, see [Secrets managed by other AWS services](https://docs.aws.amazon.com/secretsmanager/latest/userguide/service-linked-secrets.html).
HTTP Status Code: 400

 ** LimitExceededException **   
The request failed because it would exceed one of the Secrets Manager quotas.  
HTTP Status Code: 400

 ** ResourceExistsException **   
A resource with the ID you requested already exists.  
HTTP Status Code: 400

 ** ResourceNotFoundException **   
Secrets Manager can't find the resource that you asked for.  
HTTP Status Code: 400

## Examples


### Example


The following example shows how to create a new version of a secret. The `ClientRequestToken` becomes the `VersionId` of the new version. The JSON request string input and response output displays formatted code with white space and line breaks for better readability. Submit your input as a single line JSON string.

#### Sample Request


```
POST / HTTP/1.1
Host: secretsmanager.region.domain
Accept-Encoding: identity
X-Amz-Target: secretsmanager.PutSecretValue
Content-Type: application/x-amz-json-1.1
User-Agent: <user-agent-string>
X-Amz-Date: <date>
Authorization: AWS4-HMAC-SHA256 Credential=<credentials>,SignedHeaders=<headers>, Signature=<signature>
Content-Length: <payload-size-bytes>

{
  "SecretId": "MyTestDatabaseSecret",
  "SecretString": "{\"username\":\"david\",\"password\":\"EXAMPLE-PASSWORD\"}",
  "ClientRequestToken": "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE"
}
```

#### Sample Response


```
HTTP/1.1 200 OK
Date: <date>
Content-Type: application/x-amz-json-1.1
Content-Length: <response-size-bytes>
Connection: keep-alive
x-amzn-RequestId: <request-id-guid>

{
  "ARN":"arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3",
  "Name":"MyTestDatabaseSecret",
  "VersionId":"EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE",
  "VersionStages":[
      "AWSCURRENT"
  ]
}
```

## See Also


For more information about using this API in one of the language-specific AWS SDKs, see the following:
+  [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/secretsmanager-2017-10-17/PutSecretValue) 
+  [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/secretsmanager-2017-10-17/PutSecretValue)