• Key Management Service

kms
  1. Help Center
  2. Key Management Service
  3. API Reference
  4. APIs
  5. Querying Grants on a CMK

Querying Grants on a CMK

Function

This API enables you to query grants on a CMK.

URI

  • URI format

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

  • Parameter description

    Parameter

    Mandatory

    Type

    Description

    project_id

    Yes

    string

    Project ID

Requests

Request parameters

Parameter

Type

Mandatory

Description

key_id

string

Yes

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

string

No

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

string

No

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

string

No

36-byte serial number of a request message

Example: 919c82d4-8046-4722-9094-35c3c6524cff

Responses

  • Response parameters

    Parameter

    Type

    Mandatory

    Description

    grants

    JSONArray

    Yes

    List of grants

    next_marker

    string

    Yes

    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

    string

    Yes

    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

    Integer

    Yes

    This parameter indicates the total number of grants.

  • Parameters of grants

    Parameter

    Type

    Mandatory

    Description

    key_id

    string

    Yes

    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

    string

    Yes

    64-byte ID of a grant that meets the regular expression ^[A-Fa-f0-9]{64}$

    Example: 7c9a3286af4fcca5f0a385ad13e1d21a50e27b6dbcab50f37f30f93b8939827d

    grantee_principal

    string

    Yes

    32-byte ID of a user to which permissions are granted that matches the regular expression ^[a-zA-Z0-9_-]{32}$

    Example: 0d0466b00d0466b00d0466b00d0466b0

    operations

    string[]

    Yes

    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

    string

    Yes

    32-byte ID of a user who created a grant that matches the regular expression ^[a-zA-Z0-9_-]{32}$

    Example: 0d0466b00d0466b00d0466b00d0466b0

    creation_date

    string

    Yes

    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

    No

    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

    string

    No

    32-byte ID of a user who can retire a grant that matches the regular expression ^[a-zA-Z0-9_-]{32}$

    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
    }

    or

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

Status Codes

Table 1 lists the normal status code returned by the response.
Table 1 Status codes

Status Code

Status

Description

200

OK

Request processed successfully.

Exception status code. For details, see Status Codes.