Updated on 2026-09-21 GMT+08:00

Querying Retirable Grants

Function

This API is used to query the list of grants that can be retired.

Calling Method

For details, see Calling APIs.

URI

POST /v1.0/{project_id}/kms/list-retirable-grants

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. For details, see Obtaining a Project ID. Constraints N/A Range The value returned by the IAM API is used, which contains 32 characters. Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. It can be obtained by calling the IAM API. The value of X-Subject-Token in the response header is the user token. Constraints N/A Range Obtain the value by calling the IAM API for obtaining the user token. Default Value N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
limit	No	String	Definition Number of returned records for querying retirable grants Constraints If the number of records to be queried is less than the actual number of records, true is returned for the response parameter truncated, indicating that there are pagination records. Range N/A Default Value 1000
marker	No	String	Definition Start position of pagination query Constraints If truncated is true, you can send consecutive requests to obtain more records. Set marker to the value of next_marker. Range N/A Default Value N/A
sequence	No	String	Definition A 36-byte serial number of a request message, for example, 919c82d4-8046-4722-9094-35c3c6524cff. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
grants	Array of Grants objects	Definition List of retirable grants Range N/A
next_marker	String	Definition Value of marker required for the next page Range N/A
total	Integer	Definition Total number of retirable grants Range N/A
truncated	String	Definition Whether there is a next page Range true: There are more pages. false: This is the last page.

**Table 5** Grants
Parameter	Type	Description
key_id	String	Definition Key ID Range N/A
grant_id	String	Definition Grant ID Range N/A
grantee_principal	String	Definition Granted user ID Range N/A
grantee_principal_type	String	Definition Grant type Range user domain
operations	Array of strings	Definition List of granted operations Range create-datakey: Create a DEK. create-datakey-without-plaintext: Create a plaintext-free DEK. encrypt-datakey: Encrypt a DEK. decrypt-datakey: Decrypt a DEK. describe-key: Query key information. retire-grant: Retire a grant. encrypt-data: Encrypt data. decrypt-data: Decrypt data.
issuing_principal	String	Definition ID of the user who creates the grant Range N/A
creation_date	String	Definition Timestamp of the creation time, that is, the total number of seconds since January 1, 1970. Range N/A
name	String	Definition Grant name Range N/A
retiring_principal	String	Definition ID of the user who can retire a grant Range N/A

Example Requests

Query grants that can be retired. At most 1,000 grants can be returned.

{
  "limit" : "1000"
}

Example Responses

Status code: 200

Request succeeded.

{
  "grants" : [ {
    "operations" : [ "create-datakey", "describe-key" ],
    "issuing_principal" : "8b961fb414344d59825ba0c8c008c815",
    "key_id" : "737fd52b-36c4-4c91-972e-f6e202de9f6e",
    "grant_id" : "dd3f03e9229a5e47a41be6c27a630e60d5cbdbad2be89465d63109ad034db7d8",
    "grantee_principal" : "13gg44z4g2sglzk0egw0u726zoyzvrs8",
    "name" : "13gg44z4g2sglzk0egw0u726zoyzvrs8",
    "creation_date" : "1597062260000",
    "grantee_principal_type" : "user"
  } ],
  "next_marker" : "",
  "total" : 1,
  "truncated" : "false"
}

Status Codes

Status Code	Description
200	Request succeeded.

Error Codes

See Error Codes.

Parent Topic: Key Grant Management