GetSecretValue - Key Management Service - Alibaba Cloud Documentation Center

Obtains the value of a secret.

Operation description

For information about the required access policy for a RAM user or RAM role to call this API operation, see Resource Access Management.
If you do not specify a version number or stage, KMS returns the secret value of the version that is marked as ACSCurrent.
If a user-specified key is used to protect the secret value, the caller must have the kms:Decrypt permission on the corresponding master key.

This topic provides an example of how to obtain the value of a secret named secret001. The response shows that the secret value of SecretData is testdata1.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request parameters

Parameter	Type	Required	Description	Example
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 `acs:kms:${region}:${account}:secret/${secret-name}`.	secret001
VersionStage	string	No	The stage label that marks the secret version. The default value is ACSCurrent. If you specify this parameter, the secret value of the version with the specified stage label is returned. If you do not specify this parameter, the secret value of the version marked with ACSCurrent is returned. Note For RDS secrets, PolarDB secrets, Redis/Tair secrets, RAM secrets, and ECS secrets, you can obtain the secret values of only the versions that are marked with ACSPrevious and ACSCurrent.	ACSCurrent
VersionId	string	No	The version number. Note You cannot specify the VersionId parameter for RDS secrets, PolarDB secrets, Redis/Tair secrets, RAM secrets, or ECS secrets. If you set this parameter, the setting is ignored.	00000000000000000000000000000001
FetchExtendedConfig	boolean	No	Specifies whether to retrieve the extended configuration of the secret. Valid values: true: retrieves the extended configuration. false (default): does not retrieve the extended configuration. Note Generic secrets do not support extended configurations. If you set this parameter for a generic secret, the setting is ignored.	true
DryRun	string	No	Specifies whether to enable the dry run feature. true: enables the dry run feature. false (default): disables the dry run feature. The dry run feature is used to test the API call. It verifies whether you have the required permissions on the resources and whether the request parameters are valid. If you enable the dry run feature, KMS always returns a failure response that indicates the cause of the failure. The following failure causes are possible: DryRunOperationError: The request would have succeeded if the DryRun parameter was not specified. ValidationError: The parameters specified in the request are invalid. AccessDeniedError: You are not authorized to perform this operation on the KMS resource.	false

For more information about common request parameters, see Common parameters.

Response parameters

Parameter	Type	Description	Example
	object
SecretDataType	string	The type of the secret value. Valid values: text binary	binary
CreateTime	string	The time when the secret was created.	2020-02-21T15:39:26Z
VersionId	string	The version number of the secret.	00000000000000000000000000000001
NextRotationDate	string	The time when the secret is next rotated. Note This parameter is returned only if automatic rotation is enabled.	2020-07-06T18:22:03Z
SecretData	string	The value of the secret. The value is decrypted from the ciphertext by KMS and returned. For a generic secret, the value that you specified is returned. For an RDS secret or a Redis/Tair secret, the value is in the following format: `{"AccountName":"","AccountPassword":""}`. For a RAM secret, the value is in the following format: `{"AccessKeyId":"Adfdsfd","AccessKeySecret":"fdsfdsf","GenerateTimestamp": "2023-03-25T10:42:40Z"}`. For an ECS secret, the value is in one of the following formats: For a password-based credential: `{"UserName":"ecs-user","Password":"H5asdasdsads**"}` . For a key pair-based credential (the private key is in the PEM format): `{"UserName":"ecs-user","PublicKey":"ssh-rsa mKwnVix9YTFY9Rs= imported-openssh-key","PrivateKey": "d6bee1cb-2e14-4277-ba6b-73786b21**"}` . For a PolarDB secret, the value is in the following format: `{"AccountName":"","AccountPassword":""}` .	testdata1
RotationInterval	string	The interval for automatic rotation. The value is in the `integer[unit]` format. `integer` indicates the length of the time. `unit` indicates the time unit. The `unit` can be s (second). For example, a rotation period of 7 days is 604800s. Note This parameter is returned only if automatic rotation is enabled.	604800s
ExtendedConfig	string	The extended configuration of the secret. Note This parameter is returned for an RDS secret, PolarDB secret, Redis/Tair secret, RAM secret, or ECS secret only when FetchExtendedConfig is set to true.	{\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\", \"CustomData\":{} }
LastRotationDate	string	The time when the secret was last rotated. Note This parameter is returned only if the secret was rotated.	2020-07-05T08:22:03Z
RequestId	string	The ID of the request, which is a unique identifier generated by Alibaba Cloud. You can use this ID to troubleshoot issues.	6a3e9c36-1150-4881-84d3-eb8672fcafad
SecretName	string	The name of the secret.	secret001
AutomaticRotation	string	Indicates whether automatic rotation is enabled. Valid values: Enabled: Automatic rotation is enabled. Disabled: Automatic rotation is not enabled. Invalid: The rotation status is abnormal, and KMS cannot automatically rotate the secret. Note This parameter is returned only for an RDS secret, PolarDB secret, Redis/Tair secret, RAM secret, or ECS secret.	Enabled
SecretType	string	The type of the secret. Valid values: Generic: a generic secret. Rds: an RDS secret. Redis: a Redis/Tair secret. RAMCredentials: a RAM secret. ECS: an ECS secret. PolarDB: a PolarDB secret.	Generic
VersionStages	array	The stage labels that mark the secret version.
	string	The stage label that marks the secret version.	{ "VersionStage": [ "ACSCurrent" ] }

Examples

Success response

JSON format

{
  "SecretDataType": "binary",
  "CreateTime": "2020-02-21T15:39:26Z",
  "VersionId": "00000000000000000000000000000001",
  "NextRotationDate": "2020-07-06T18:22:03Z",
  "SecretData": "testdata1",
  "RotationInterval": "604800s",
  "ExtendedConfig": "{\\\"SecretSubType\\\":\\\"SingleUser\\\", \\\"DBInstanceId\\\":\\\"rm-uf667446pc955****\\\",  \\\"CustomData\\\":{} }",
  "LastRotationDate": "2020-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 error message returned because the specified CMK does not exist.
404	Forbidden.ResourceNotFound	Resource not found.	The resource is not found.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.