Querying the Grant List

Function

This API is used to query the users who have been granted the permissions of a key.

Calling Method

For details, see Calling APIs.

URI

POST /v1.0/{project_id}/kms/list-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
key_id	Yes	String	Definition Key ID Constraints The value must be a 36-byte ID. The value must match the regular expression ^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$. Range N/A Default Value N/A
limit	No	String	Definition Number of returned records 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 Grant list Range N/A
next_marker	String	Definition Value of marker required for the next page Range N/A
truncated	String	Definition Whether there is a next page Range true: There are more pages. false: This is the last page.
total	Integer	Definition Total number of grants Range N/A

**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 the grant list of the key whose ID is 0d0466b0-e727-4d9c-b35d-f84bb474a37f.

{
  "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f"
}

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"
}