GetSecretValue - Key Management Service - Alibaba Cloud Documentation Center

If you do not specify the version number or stage label, Key Management Service (KMS) returns the secret value of the ACSCurrent version.

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

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	GetSecretValue	The operation that you want to perform. Set the value to GetSecretValue.
SecretName	String	Yes	secret001	The Alibaba Cloud Resource Name (ARN) of the secret or secret resource. Note When you access a secret within another Alibaba Cloud account, you must enter the ARN of the secret. The ARN 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 the parameter is specified, KMS returns the secret value of the specified stage label. If the parameter is not specified, KMS returns the secret value whose stage label is ACSCurrent. Note You can only query secret values whose stage label is ACSPrevious and ACSCurrent for Resource Access Management (RAM) secrets, ApsaraDB RDS secrets, and Elastic Compute Service (ECS) secrets.
VersionId	String	No	v1	The version ID. Note You cannot specify VersionId for ApsaraDB RDS, RAM, or ECS secrets. If you set VersionId, the parameter is ignored.
FetchExtendedConfig	Boolean	No	true	Specifies whether to obtain the extended configuration of the secret. Valid values: true false (default) Note Generic secrets do not support extended configurations. The parameter is ignored for generic secrets.

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: text binary
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 The parameter is returned if automatic key rotation is enabled.
SecretData	String	testdata1	The secret value. The parameter is returned after KMS decrypts the stored secret value ciphertext. For a generic secret, the specified secret value is returned. For an ApsaraDB RDS secret, the secret value in the `{"AccountName":"","AccountPassword":""}` format is returned. For a RAM secret, the secret value in the `{"AccessKeyId":"Adfdsfd","AccessKeySecret":"fdsfdsf","GenerateTimestamp": "2023-03-25T10:42:40Z"}` format is returned. For an ECS secret, the secret value is returned in the following format: Password: `{"UserName":"ecs-user","Password":"H5asdasdsads**"}` Public-private key pair: (private key in the PEM format): `{"UserName":"ecs-user","PublicKey":"ssh-rsa mKwnVix9YTFY9Rs= imported-openssh-key","PrivateKey": "d6bee1cb-2e14-4277-ba6b-73786b21**"}`.
RotationInterval	String	604800s	The interval for automatic rotation. The value is in the `integer[unit]` format. `integer` indicates the length of time. `unit`: indicates the time unit. The `unit` field has a fixed value of s. For example, if the value is 604800s, automatic rotation is performed at a 7-day interval. Note The parameter is returned if automatic key rotation is enabled.
ExtendedConfig	String	{\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\", \"CustomData\":{} }	The extended configuration of the secret. Note If FetchExtendedConfig is set to true, the parameter is returned only for ApsaraDB RDS secrets, RAM secrets, and ECS secrets.
LastRotationDate	String	2023-07-05T08:22:03Z	The time when the last rotation is performed. Note The parameter is returned if the secret is rotated.
RequestId	String	6a3e9c36-1150-4881-84d3-eb8672fcafad	The ID of the request, which is used to locate and troubleshoot issues.
SecretName	String	secret001	The secret name.
AutomaticRotation	String	Enabled	Indicates whether automatic rotation is enabled. Valid values: Enabled: Automatic rotation is enabled. Disabled: Automatic rotation is disabled. Invalid: The status of automatic rotation is abnormal. In this case, KMS cannot automatically rotate the secret. Note The parameter is returned only for ApsaraDB RDS secrets, RAM secrets, or ECS secrets.
SecretType	String	Generic	The type of the secret. Valid values: Generic: generic secret Generic: ApsaraDB RDS secret RAMCredentials: RAM secret ECS: ECS secret
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
&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

HTTP status code	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.