ListGrants
Gets a list of all grants for the specified KMS key.
Description
The ListGrants operation gets a list of all grants for the specified KMS key. A grant is a policy instrument that allows QKMS principals to use KMS keys in cryptographic operations. A grant also can allow QKMS principals to view a KMS key (DescribeKey) and create and manage grants.
note
- You must specify the KMS key in all requests.
- You can filter the grant list by grant ID or grantee principal.
- The GranteePrincipal field in the grant does not contain the grantee principal's ARN until after the grant is used.
Request Syntax
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| Content-Type | Must be "application/x-amz-json-1.1" | Yes | string |
| X-Amz-Target | Must be "TrentService.ListGrants" | Yes | string |
Request Body
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | The identifier of the KMS key. The value can be the ID or ARN of a KMS key. | Yes | string |
| Limit | Use this parameter to specify the maximum number of items to return. When this value is present, QKMS does not return more than the specified number of items, but it might return fewer. | No | integer |
| Marker | Use this parameter in a subsequent request after you receive a response with truncated results. Set it to the value of NextMarker from the truncated response you just received. | No | string |
| GrantId | Returns only the grant with the specified grant ID. | No | string |
| GranteePrincipal | Returns only grants where the specified principal is the grantee principal for the grant. | No | string |
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.ListGrants
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Limit": 20,
"Marker": "eyJlbmNyeXB0ZWREYXRhIjpbMTIsMzQsNTYsNzgsOTBdfQ=="
}
Values in italics indicate user input and should be replaced with actual values.
Response Elements
| Name | Description | Required | Type |
|---|---|---|---|
| Grants | A list of grants. | No | String |
| NextMarker | When Truncated is true, this value is present and contains the value to use for the Marker parameter in a subsequent request. | No | String |
| Truncated | A flag that indicates whether there are more items in the list. When this value is true, the list in this response is truncated. To get more items, pass the value of the NextMarker element in subsequent requests. | No | String |
Special Errors
| Error Code | Description |
|---|---|
| DependencyTimeoutException | The system timed out while trying to fulfill the request. |
| InvalidArnException | The request was rejected because a specified ARN was not valid. |
| InvalidGrantIdException | The request was rejected because the specified grant ID is not valid. |
| InvalidMarkerException | The request was rejected because the marker that specifies where pagination should next begin is not valid. |
| KMSInternalException | An internal error occurred. |
| KMSInvalidStateException | The request was rejected because the key state is not valid for this operation. |
| NotFoundException | The request was rejected because the specified entity or resource could not be found. |
Permissions
To use the ListGrants operation, you must have the following permissions:
kms:ListGrantson the KMS key (specified in the policy)
Try It Out
Test ListGrants
List grants for a KMS key.
Coming Soon
This feature is currently under development and will be available soon.