Stores the secret value of a new version into a secret.
This operation is used to store the secret values of new versions. It cannot be used to modify the secret value of an existing version.
By default, the newly stored secret value is marked with ACSCurrent, and the mark for the previous version of the secret value is changed from ACSCurrent to ACSPrevious. If you specify the VersionStage parameter, the newly stored secret value is marked with the stage label that you specify.
You must specify a version number when you call the operation. Secrets Manager performs operations based on the following rules:
- If the specified version number does not exist in the secret, Secrets Manager creates the version and stores the secret value.
- If the specified version number already exists in the secret and the secret value of the existing version is the same as the secret value that you specify, Secrets Manager ignores the request and returns a success message. The request is idempotent.
- If the specified version number already exists in the secret but the secret value of the existing version is different from the secret value that you specify, Secrets Manager rejects the request and returns a failure message.
Limits: This operation is available only for standard secrets.
In this example, the secret value of a new version is stored into the secret001
secret. The VersionId
parameter is set to 00000000000000000000000000000000203
as the new version, and the SecretData
parameter is set to importantdata
.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | PutSecretValue |
The operation that you want to perform. Set the value to PutSecretValue. |
VersionId | String | Yes | 00000000000000000000000000000000203 |
The new version of the secret value. Version numbers must be unique in each secret. |
SecretName | String | Yes | secret001 |
The name of the secret. |
SecretData | String | Yes | importantdata |
The secret value. The value is encrypted and then stored in the new version. |
SecretDataType | String | No | text |
The type of the secret value. Valid values:
|
VersionStages | String | No | ["ACSCurrent","ACSNext"] |
The stage labels that are used to mark the new version. If you do not specify this parameter, Secrets Manager marks the new version with ACSCurrent. |
For more information about common request parameters, see Common parameters.
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
SecretName | String | secret001 |
The name of the secret. |
VersionId | String | 00000000000000000000000000000000203 |
The new version of the secret value. |
RequestId | String | f94ec9d3-2d10-4922-9a5c-5dcd5ebcb5e8 |
The ID of the request, which is used to locate and troubleshoot issues. |
VersionStages | Array of String | { "VersionStage": [ "ACSCurrent", "ACSNext" ] } |
The stage labels that are used to mark the new version. |
Examples
Sample requests
http(s)://[Endpoint]/?Action=PutSecretValue
&VersionId=00000000000000000000000000000000203
&SecretName=secret001
&SecretData=importantdata
&SecretDataType=text
&VersionStages=["ACSCurrent","ACSNext"]
&Common request parameters
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<PutSecretValueResponse>
<SecretName>secret001</SecretName>
<VersionId>00000000000000000000000000000000203</VersionId>
<RequestId>f94ec9d3-2d10-4922-9a5c-5dcd5ebcb5e8</RequestId>
<VersionStages>{ "VersionStage": [ "ACSCurrent", "ACSNext" ] }</VersionStages>
</PutSecretValueResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"SecretName" : "secret001",
"VersionId" : "00000000000000000000000000000000203",
"RequestId" : "f94ec9d3-2d10-4922-9a5c-5dcd5ebcb5e8",
"VersionStages" : [ "{ \"VersionStage\": [ \"ACSCurrent\", \"ACSNext\" ] }" ]
}
Error codes
For a list of error codes, visit the API Error Center.