Querying Grants on a CMK

Updated on 2022-12-06 GMT+08:00

View PDF

Function

This API enables you to query grants on a CMK.

URI

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

Parameter description

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID

Requests

**Table 2** Request parameters
Parameter	Mandatory	Type	Description
key_id	Yes	String	36-byte ID of a CMK that matches the regular expression ^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$ Example: 0d0466b0-e727-4d9c-b35d-f84bb474a37f
limit	No	String	This parameter specifies the number of entries returned. If the specified number is smaller than the actual number of existing entries, true will be returned for the response parameter truncated, indicating that the query results will be displayed in separate pages. The value is within the range of the maximum number of grants, for example, 100.
marker	No	String	This parameter marks the starting location in a pagination query. If the truncated value is true, you can send consecutive requests to obtain more record entries. The marker value must be set to the next_marker value in the response, for example, 10.
sequence	No	String	36-byte serial number of a request message Example: 919c82d4-8046-4722-9094-35c3c6524cff

Responses

**Table 3** Response parameters
Parameter	Mandatory	Type	Description
grants	Yes	Array of objects	Grant list. For details, see Table 4.
next_marker	Yes	String	This parameter indicates the marker value required for obtaining the next page of query results. If the truncated value is false, the next_marker parameter is left blank.
truncated	Yes	String	This parameter indicates whether there are more results displayed in another page. If the value is true, there are more results. If the value is false, the current page is the last page.
total	Yes	Integer	This parameter indicates the total number of grants.

**Table 4** **grants** field description
Parameter	Mandatory	Type	Description
key_id	Yes	String	36-byte ID of a CMK that matches the regular expression ^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$ Example: 0d0466b0-e727-4d9c-b35d-f84bb474a37f
grant_id	Yes	String	64-byte ID of a grant that meets the regular expression ^[A-Fa-f0-9]{64}$ Example: 7c9a3286af4fcca5f0a385ad13e1d21a50e27b6dbcab50f37f30f93b8939827d
grantee_principal	Yes	String	Indicates the ID of the authorized user. The value is between 1 to 64 bytes and meets the regular expression "^[a-zA-Z0-9]{1,64}$". Example: 0d0466b00d0466b00d0466b00d0466b0
operations	Yes	Array of strings	Permissions that can be granted. Values: create-datakey, create-datakey-without-plaintext, encrypt-datakey, decrypt-datakey, describe-key, create-grant, retire-grant create-grant cannot be the only value.
issuing_principal	Yes	String	Indicates the ID of the user who created the grant. The value is between 1 to 64 bytes and meets the regular expression "^[a-zA-Z0-9]{1,64}$". Example: 0d0466b00d0466b00d0466b00d0466b0
creation_date	Yes	String	Creation time. The value is a timestamp expressed in the number of seconds since 00:00:00 UTC on January 1, 1970. Example: 1497341531000
name	No	String	Name of a grant which can be 1 to 255 characters in length and matches the regular expression ^[a-zA-Z0-9:/_-]{1,255}$
retiring_principal	No	String	Indicates the ID of the retiring user. The value is between 1 to 64 bytes and meets the regular expression "^[a-zA-Z0-9]{1,64}$". Example: 0d0466b00d0466b00d0466b00d0466b0

Examples

The following example describes how to query the grant list of a CMK whose ID is 0d0466b0-e727-4d9c-b35d-f84bb474a37f.

Example request

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

Example response

{
    "grants": [
     {"key_id": "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e",
      "grant_id": "7c9a3286af4fcca5f0a385ad13e1d21a50e27b6dbcab50f37f30f93b8939827d",
      "operations": 
      ["describe-key","create-datakey", "encrypt-datakey"],
      "grantee_principal":"13gg44z4g2sglzk0egw0u726zoyzvrs8",
      "retiring_principal":"13gg44z4g2sglzk0egw0u726zoyzvrs8",
      "issuing_principal":"e4hkeeea506ex3wgnzyhi656n8hx8xa3",
      "name":"my_grant",
      "creation_date":"1497341531000",
      }],
    "next_marker": "",
    "truncated": "false",
    "total":1
}

{
    "error": {
        "error_code": "KMS.XXXX",
        "error_msg": "XXX"
    }
}

Status Codes

Table 5 lists the normal status code returned by the response.

**Table 5** Status codes
Status Code	Status	Description
200	OK	Request processed successfully.

Exception status code. For details, see Status Codes.

Parent topic: APIs

Previous topic: Retiring a Grant

Next topic: Querying Grants That Can Be Retired

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot