All Products
Search
Document Center

Key Management Service:GetSecretValue

Last Updated:Sep 11, 2024

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

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 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:

  • true
  • false (default)
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:

  • true
  • false (default)

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:

  • DryRunOperationError: The request passes the dry run. If you do not configure the DryRun parameter and retain the other parameter configurations to call the same operation, the operation will be performed.
  • ValidationError: A parameter value in the request is invalid.
  • AccessDeniedError: You do not have the permissions to access the resources that you want to manage.

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 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.

  • For a generic secret, the specified secret value is returned.
  • For an ApsaraDB RDS, ApsaraDB for Redis, or Tair secret, the secret value is returned in the {"AccountName":"","AccountPassword":""} format.
  • For a RAM secret, the secret value is returned in the {"AccessKeyId":"Adfdsfd","AccessKeySecret":"fdsfdsf","GenerateTimestamp": "2023-03-25T10:42:40Z"} format.
  • For an ECS secret, the secret value is returned in the following format:
    • Password: {"UserName":"ecs-user","Password":"H5asdasdsads****"}.
    • Public-private key pair with the 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 time period and unit indicates the unit of the time period. The value of unit is fixed as s, which indicates seconds. If the value is 604800s, automatic rotation is performed at a 7-day interval.

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:

  • 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 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:

  • Generic: generic secret.
  • Rds: ApsaraDB RDS secret.
  • Redis: ApsaraDB for Redis or Tair 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
&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.