Stores a new version of a secret value for a generic secret.
Operation description
-
For information about the access policy required for a RAM user or RAM role to call this OpenAPI operation, see Resource Access Management.
-
This operation supports only generic secrets. Each generic secret can have a maximum of 10 versions. If the number of versions exceeds the limit, KMS deletes the earliest version.
-
By default, the new secret value is marked with ACSCurrent, and the previous version that was marked with ACSCurrent is marked with ACSPrevious. You can specify the VersionStage parameter to overwrite this default behavior.
-
This operation stores a new version of a secret value. You cannot use it to modify an existing version of a secret value. You must specify a version number when you store a new version. KMS processes requests based on the following rules:
If the version number does not exist in the secret, KMS creates a new version and stores the secret value.
If the version number already exists in the secret, KMS compares the secret value in the request with the stored value. If the values are the same, the request is ignored and a success message is returned. This makes the operation idempotent. If the values are different, the request is rejected.
This topic provides an example of how to store a new version of a secret value for the secret named secret001. The new version number (VersionId) is v3 and the secret value (SecretData) is importantdata.
Try it now
Test
RAM authorization
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| VersionId |
string |
Yes |
The version number of the secret. The value must be unique in the secret. |
00000000000000000000000000000000203 |
| SecretName |
string |
Yes |
The name or Alibaba Cloud Resource Name (ARN) of the secret. Note
When you access a secret in another Alibaba Cloud account, you must specify the ARN of the secret. The ARN of a secret is in the format of |
secret001 |
| SecretData |
string |
Yes |
The secret value. The value is encrypted and stored in the specified new version. |
importantdata |
| SecretDataType |
string |
No |
The type of the secret value. Valid values:
|
text |
| VersionStages |
string |
No |
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. |
["ACSCurrent","ACSNext"] |
For more information about common request parameters, see Common parameters.
Response parameters
|
Parameter |
Type |
Description |
Example |
|
object |
|||
| SecretName |
string |
The name of the secret. |
secret001 |
| VersionId |
string |
The version number of the secret. |
00000000000000000000000000000000203 |
| RequestId |
string |
The ID of the request, which is a unique identifier generated by Alibaba Cloud. You can use this ID to troubleshoot issues. |
f94ec9d3-2d10-4922-9a5c-5dcd5ebcb5e8 |
| VersionStages |
object |
||
| VersionStage |
array |
The stage labels of the secret version. |
|
|
string |
The stage label of the secret version. |
{ "VersionStage": [ "ACSCurrent", "ACSNext" ] } |
Examples
Success response
JSON format
{
"SecretName": "secret001",
"VersionId": "00000000000000000000000000000000203",
"RequestId": "f94ec9d3-2d10-4922-9a5c-5dcd5ebcb5e8",
"VersionStages": {
"VersionStage": [
"{ \"VersionStage\": [ \"ACSCurrent\", \"ACSNext\" ] }"
]
}
}Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidParameter | some of the specified parameters "\" is not valid | |
| 400 | Rejected.LimitExceeded | exceed secret limits error | |
| 500 | InternalFailure | Internal Failure | |
| 403 | Forbidden.NoPermission | This operation is forbidden by permission system | |
| 404 | Forbidden.ResourceNotFound | Resource not found | |
| 409 | Rejected.ResourceExist | The request was rejected becasue key already exsit |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.