Queries a secret value.
If you do not specify the version number or stage label, Key Management Service (KMS) automatically returns the secret value whose stage label is ACSCurrent.
If the secret value is encrypted by using a key, you must have the kms:Decrypt
permission on the key.
In this example, the value of the secret named secret001
is obtained. The testdata1
secret value is returned in the SecretData
parameter.
Debugging
Request parameters
Parameter |
Type |
Required |
Example |
Description |
Action | String | Yes | GetSecretValue | The operation that you want to perform. Set the value to GetSecretValue. |
SecretName | String | Yes | secret001 | The name or Alibaba Cloud Resource Name (ARN) of the secret. Note If you access a secret within another Alibaba Cloud account, you must enter the ARN of the secret. The ARN of the secret is in the acs:kms:${region}:${account}:secret/${secret-name} format. |
VersionStage | String | No | ACSCurrent | The stage label that marks the secret version. Default value: ACSCurrent. If you specify this parameter, KMS returns the secret value with the specified stage label. If you do not specify this parameter, KMS automatically returns the secret value whose stage label is ACSCurrent. Note You can query only secret values whose stage label is ACSPrevious or ACSCurrent for Resource Access Management (RAM) secrets, ApsaraDB RDS secrets, ApsaraDB for Redis secrets, Tair secrets, and Elastic Compute Service (ECS) secrets. |
VersionId | String | No | v1 | The version ID. Note You cannot specify the VersionId parameter for ApsaraDB RDS secrets, ApsaraDB for Redis secrets, Tair secrets, RAM secrets, or ECS secrets. If you specify the VersionId parameter, the parameter is ignored. |
FetchExtendedConfig | Boolean | No | true | Specifies whether to obtain the extended configuration of the secret. Valid values:
Note Generic secrets do not support extended configurations. This parameter is ignored for generic secrets. |
DryRun | String | No | false | Specifies whether to perform a dry run. Valid values:
A dry run is used for testing in API calls. You can perform a dry run to check whether you have the permissions to access the resources that you want to manage and whether the request parameters are correctly configured. If you set DryRun to true in the request, KMS always returns an error code that indicates the cause of the error. KMS may return the following error codes:
|
For more information about common request parameters, see Common parameters.
Response parameters
Parameter |
Type |
Example |
Description |
SecretDataType | String | binary | The type of the secret value. Valid values:
|
CreateTime | String | 2024-02-21T15:39:26Z | The time when the secret is created. |
VersionId | String | v1 | The version number of the secret. |
NextRotationDate | String | 2024-07-06T18:22:03Z | The time when the next rotation is performed. Note If automatic rotation is enabled, this parameter is returned. |
SecretData | String | testdata1 | The secret value. This parameter is returned after KMS decrypts the stored secret value ciphertext.
|
RotationInterval | String | 604800s | The interval for automatic rotation. The value is in the Note If automatic rotation is enabled, this parameter is returned. |
ExtendedConfig | String | {\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\", \"CustomData\":{} } | The extended configuration of the secret. Note If FetchExtendedConfig is set to true, this parameter is returned only for ApsaraDB RDS secrets, ApsaraDB for Redis secrets, Tair secrets, RAM secrets, and ECS secrets. |
LastRotationDate | String | 2023-07-05T08:22:03Z | The time when the last rotation is performed. Note If the secret is rotated, this parameter is returned. |
RequestId | String | 6a3e9c36-1150-4881-84d3-eb8672fcafad | The request ID. |
SecretName | String | secret001 | The secret name. |
AutomaticRotation | String | Enabled | Indicates whether automatic rotation is enabled. Valid values:
Note This parameter is returned only for ApsaraDB RDS secrets, ApsaraDB for Redis secrets, Tair secrets, RAM secrets, and ECS secrets. |
SecretType | String | Generic | The type of the secret. Valid values:
|
VersionStages | Array of String | { "VersionStage": [ "ACSCurrent" ] } | The stage labels that mark the secret version. |
Examples
Sample requests
http(s)://[Endpoint]/?Action=GetSecretValue
&SecretName=secret001
&VersionStage=ACSCurrent
&VersionId=v1
&FetchExtendedConfig=true
&DryRun=false
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<GetSecretValueResponse>
<SecretDataType>binary</SecretDataType>
<CreateTime>2024-02-21T15:39:26Z</CreateTime>
<VersionId>v1</VersionId>
<NextRotationDate>2024-07-06T18:22:03Z</NextRotationDate>
<SecretData>testdata1</SecretData>
<RotationInterval>604800s</RotationInterval>
<ExtendedConfig>{\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\", \"CustomData\":{} }</ExtendedConfig>
<LastRotationDate>2023-07-05T08:22:03Z</LastRotationDate>
<RequestId>6a3e9c36-1150-4881-84d3-eb8672fcafad</RequestId>
<SecretName>secret001</SecretName>
<AutomaticRotation>Enabled</AutomaticRotation>
<SecretType>Generic</SecretType>
<VersionStages>{ "VersionStage": [ "ACSCurrent" ] }</VersionStages>
</GetSecretValueResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"SecretDataType" : "binary",
"CreateTime" : "2024-02-21T15:39:26Z",
"VersionId" : "v1",
"NextRotationDate" : "2024-07-06T18:22:03Z",
"SecretData" : "testdata1",
"RotationInterval" : "604800s",
"ExtendedConfig" : "{\\\"SecretSubType\\\":\\\"SingleUser\\\", \\\"DBInstanceId\\\":\\\"rm-uf667446pc955****\\\", \\\"CustomData\\\":{} }",
"LastRotationDate" : "2023-07-05T08:22:03Z",
"RequestId" : "6a3e9c36-1150-4881-84d3-eb8672fcafad",
"SecretName" : "secret001",
"AutomaticRotation" : "Enabled",
"SecretType" : "Generic",
"VersionStages" : [ "{ \"VersionStage\": [ \t\"ACSCurrent\" \t] }" ]
}
Error codes
HttpCode |
Error code |
Error message |
Description |
403 | Forbidden.DKMSInstanceStateInvalid | The DKMS instance state is invalid. | Your dedicated KMS instance is invalid. |
403 | Forbidden.DKMSInstanceNotFound | The specified DKMS Instance is not found. | Your dedicated KMS instance is not found. |
404 | Forbidden.KeyNotFound | The specified Key is not found. | The specified key does not exist. |
404 | Forbidden.ResourceNotFound | Resource not found. | The resource is not found. |
For a list of error codes, see Service error codes.