BatchGetSecretValue - Key Management Service - Alibaba Cloud Documentation Center

Retrieves secret values in batches.

Operation description

For details about the access policy required for a Resource Access Management (RAM) user or RAM role to invoke this operation, see Access control.
If you do not specify a version number or version stage, KMS returns the secret value of the version marked as ACSCurrent by default.
The caller must have the kms:GetSecretValue permission on all secrets in the batch.
If a secret uses a customer master key to protect the secret value, the caller must also have the kms:Decrypt permission on the corresponding master key.

This topic provides an example of how to retrieve the secret value of a secret named secret001. The response shows that the secret value 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 syntax

GET  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
SecretsList	array<object>	No	The list of secret information. You can query up to 20 different secrets at a time.
	object	No
SecretName	string	Yes	The secret name or secret Alibaba Cloud Resource Name (ARN). Note When accessing a secret in another Alibaba Cloud account, you must specify the secret ARN. The format of a secret ARN is `acs:kms:${region}:${account}:secret/${secret-name}`.	secret001
VersionStage	string	No	The version stage. Default value: ACSCurrent. If you specify this parameter, the secret value of the specified version stage is returned. If you do not specify this parameter, the secret value of the ACSCurrent version stage is returned. Note For ApsaraDB RDS secrets, PolarDB secrets, Redis/Tair secrets, RAM secrets, and ECS secrets, you can retrieve only the secret values of the ACSPrevious and ACSCurrent versions.	ACSCurrent
VersionId	string	No	The version number.	v1
FetchExtendedConfig	string	No	Specifies whether to retrieve the extended configuration of the secret. Valid values: true: Retrieve the extended configuration. false (default): Do not retrieve the extended configuration. Note Generic secrets do not support extended configurations. This parameter is ignored for generic secrets. Valid values: true : Retrieve the extended configuration. false : Do not retrieve the extended configuration.	true

Response elements

Element	Type	Description	Example
	object	Schema of Response
RequestId	string	The request ID.	8252db58-2036-408c-a3d5-56e656dc2551
SecretValues	array<object>	The list of secrets that are successfully retrieved.
	array<object>
SecretDataType	string	The type of the secret value. Valid values: text binary	binary
CreateTime	string	The time when the secret was created (UTC).	2024-02-21T15:39:26Z
VersionId	string	The version number of the secret.	v1
NextRotationDate	string	The time of the next rotation (UTC). Note This parameter is returned only when automatic rotation is enabled.	2024-07-06T18:22:03Z
SecretData	string	The secret value. KMS decrypts the stored ciphertext secret value and returns this parameter. A generic secret returns the secret value that you specified. An ApsaraDB RDS secret or Redis/Tair secret returns the secret value in the following format: `{"AccountName":"","AccountPassword":""}`. A RAM secret returns the secret value in the following format: `{"AccessKeyId":"Adfdsfd","AccessKeySecret":"fdsfdsf","GenerateTimestamp": "2023-03-25T10:42:40Z"}`. An ECS secret returns the secret value in the following formats: Password-type secret: `{"UserName":"ecs-user","Password":"H5asdasdsads**"}`. Public-private key-type secret (private key in PEM format): `{"UserName":"ecs-user","PublicKey":"ssh-rsa mKwnVix9YTFY9Rs= imported-openssh-key","PrivateKey": "d6bee1cb-2e14-4277-ba6b-73786b21**"}`. A PolarDB secret returns the secret value in the following format: `{"AccountName":"","AccountPassword":""}`.	testdata1
RotationInterval	string	The interval for automatic rotation of the secret. The format is integer[unit], where integer specifies the duration and unit specifies the time unit. The value of unit is s (seconds). For example, a rotation interval of 7 days is 604800s. Note This parameter is returned only when automatic rotation is enabled.	604800s
ExtendedConfig	string	The extended configuration of the secret. Note This parameter is returned only for ApsaraDB RDS secrets, PolarDB secrets, Redis/Tair secrets, RAM secrets, or ECS secrets when FetchExtendedConfig is set to true.	{\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\", \"CustomData\":{} }
LastRotationDate	string	The time of the most recent rotation (UTC). Note This parameter is returned only when the secret has been rotated.	2023-07-05T08:22:03Z
RequestId	string	The ID of this request, which is a unique identifier generated by Alibaba Cloud for troubleshooting purposes.	8252db58-2036-408c-a3d5-56e656dc2551
SecretName	string	The secret name.	secret001
AutomaticRotation	string	Indicates whether automatic rotation is enabled. Valid values: Enabled: Automatic rotation is enabled. Disabled: Automatic rotation is disabled. Invalid: The rotation status is abnormal. KMS cannot automatically rotate the secret. Note This parameter is returned only for ApsaraDB RDS secrets, PolarDB secrets, Redis/Tair secrets, RAM secrets, or ECS secrets.	Enabled
SecretType	string	The type of the secret. Valid values: Generic: generic secret. Rds: ApsaraDB RDS secret. Redis: Redis/Tair secret. RAMCredentials: RAM secret. ECS: ECS secret. PolarDB: PolarDB secret.	Generic
VersionStages	object	The version stages of the secret.
VersionStage	array
	string		{ "VersionStage": [ "ACSCurrent" ] }
Errors	array<object>	The list of errors for secrets that failed to be retrieved.
	object	None.
SecretName	string	The secret name.	secret002
HttpStatus	integer	The HTTP status code returned for the error.	404
Code	string	The service error code.	Forbidden.ResourceNotFound
Message	string	The error message for the failed secret retrieval.	Resource not found.

Examples

Success response

JSON format

{
  "RequestId": "8252db58-2036-408c-a3d5-56e656dc2551",
  "SecretValues": [
    {
      "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": "8252db58-2036-408c-a3d5-56e656dc2551",
      "SecretName": "secret001",
      "AutomaticRotation": "Enabled",
      "SecretType": "Generic",
      "VersionStages": {
        "VersionStage": [
          "{ \"VersionStage\": [ \"ACSCurrent\" ] }"
        ]
      }
    }
  ],
  "Errors": [
    {
      "SecretName": "secret002",
      "HttpStatus": 404,
      "Code": "Forbidden.ResourceNotFound",
      "Message": "Resource not found."
    }
  ]
}

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.