Querying the Grant List

Updated on 2025-03-25 GMT+08:00

View PDF

Function

Description: This API is used to query the grant list of a key.

URI

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

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

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It can be obtained by calling the IAM API that is used for obtaining a user token. The value of X-Subject-Token in the response header is the user token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
key_id	Yes	String	Key ID. It should be 36 bytes and match 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	Number of returned grant records. If the number of retrieved results is greater than this value, true is returned for the response parameter truncated, indicating that multiple pages of results are retrieved. The value cannot exceed the maximum number of grants. Example: 100
marker	No	String	Start position of pagination query. If truncated is true in the response, you can send consecutive requests to obtain more records. Set marker to the value of next_marker in the response. Example: 10
sequence	No	String	36-byte sequence number of a request message. Example: 919c82d4-8046-4722-9094-35c3c6524cff

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
grants	Array of Grants objects	Grant list. For details, see the parameter description of the grant field.
next_marker	String	Value of marker used for obtaining the next page of results. If truncated is false, next_marker is left blank.
truncated	String	Whether there is a next page of results: true: There is a next page. false: This is the last page.
total	Integer	Total number of grants.

**Table 5** Grants
Parameter	Type	Description
key_id	String	Key ID.
grant_id	String	Grant ID, which contains 64 bytes.
grantee_principal	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
grantee_principal_type	String	Authorization type. Values: user or domain
operations	Array of strings	List of granted operations. Values: create-datakey, create-datakey-without-plaintext, encrypt-datakey, decrypt-datakey, describe-key, create-grant, retire-grant, encrypt-data, decrypt-data A value containing only create-grant is invalid. create-datakey: Creating a DEK create-datakey-without-plaintext: Creating a Plaintext-free DEK encrypt-datakey: Encrypting a DEK decrypt-datakey: Decrypting a DEK describe-key: Querying Key Details retire-grant: Creating a Grant encrypt-data: Encrypting Data decrypt-data: Decrypting Data
issuing_principal	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	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	String	Grant name. The value can contain 1 to 255 characters and matches the regular expression ^[a-zA-Z0-9:/_-]{1,255}$.
retiring_principal	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

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 7** ErrorDetail
Parameter	Type	Description
error_code	String	Error code returned for an error request.
error_msg	String	Error information returned for an error request.

Status code: 401

**Table 8** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 9** ErrorDetail
Parameter	Type	Description
error_code	String	Error code returned for an error request.
error_msg	String	Error information returned for an error request.

Status code: 403

**Table 10** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 11** ErrorDetail
Parameter	Type	Description
error_code	String	Error code returned for an error request.
error_msg	String	Error information returned for an error request.

Status code: 404

**Table 12** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 13** ErrorDetail
Parameter	Type	Description
error_code	String	Error code returned for an error request.
error_msg	String	Error information returned for an error request.

Status code: 500

**Table 14** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 15** ErrorDetail
Parameter	Type	Description
error_code	String	Error code returned for an error request.
error_msg	String	Error information returned for an error request.

Status code: 502

**Table 16** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 17** ErrorDetail
Parameter	Type	Description
error_code	String	Error code returned for an error request.
error_msg	String	Error information returned for an error request.

Status code: 504

**Table 18** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 19** ErrorDetail
Parameter	Type	Description
error_code	String	Error code returned for an error request.
error_msg	String	Error information returned for an error request.

Example Requests

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

Example Responses

Status code: 200

Request processing 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 processing succeeded.
400	Invalid request parameters.
401	You must enter a username and password to access the requested page.
403	Authentication failed.
404	The requested resource does not exist or is not found.
500	Internal service error.
502	Failed to complete the request. The server received an invalid response.
504	Gateway timed out.