PutSecretValue - Key Management Service - Alibaba Cloud Documentation Center

Stores the secret value of a new version into a secret.

Note

Each generic secret can have up to 10 versions. If a generic secret has more than 10 versions, KMS automatically deletes the earliest version in a rolling manner.

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 labeled as ACSCurrent, and the label for the previous version of the secret value is changed from ACSCurrent to ACSPrevious. If you set VersionStage, the newly stored secret value is labeled as the stage label that you specify.

You must specify a version number when you call the operation. KMS performs operations based on the following rules:

If the specified version number does not exist in the secret, KMS 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, KMS 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, KMS rejects the request and returns a failure message.

Limits: This operation is available only for generic 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

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

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 secret name.
SecretData	String	Yes	importantdata	The secret value. The secret value is encrypted and then stored in the new version.
SecretDataType	String	No	text	The type of the secret value. Valid values: text (default) binary
VersionStages	String	No	["ACSCurrent","ACSNext"]	The stage labels that are used to mark the new version. If you do not specify this parameter, KMS 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 secret name.
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, see Service error codes.