ListRetirableGrants

Gets a list of all grants for which the specified principal is the retiring principal.

Description

The ListRetirableGrants operation returns a list of all grants for which the specified principal is the retiring principal. A retiring principal is a principal that can retire a grant. For more information about grants, see Using Grants.

note

• The retiring principal must be specified.
• The response might include multiple grants for the same KMS key.
• When there are multiple grants, use the GrantId to distinguish between them.

Request Syntax

POST / HTTP/1.1

Content-Type: application/x-amz-json-1.1

X-Amz-Target: TrentService.ListRetirableGrants

{ "Limit": 20, "Marker": "eyJlbmNyeXB0ZWREYXRhIjpbMTIsMzQsNTYsNzgsOTBdfQ==", "RetiringPrincipal": "arn:aws:iam::111122223333:role/AdminRole" }

Values in italics indicate user input and should be replaced with actual values.

Request Parameters

Headers

Name	Description	Required	Type
Content-Type	Must be "application/x-amz-json-1.1"	Yes	string
X-Amz-Target	Must be "TrentService.ListRetirableGrants"	Yes	string

Request Body

Name	Description	Required	Type
RetiringPrincipal	The principal that can retire the grant. To specify the principal, use the Amazon Resource Name (ARN) of an AWS principal.	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

Examples

Example 1: List retirable grants for a principal

POST / HTTP/1.1

Content-Type: application/x-amz-json-1.1

X-Amz-Target: TrentService.ListRetirableGrants

{ "RetiringPrincipal": "arn:aws:iam::111122223333:role/AdminRole" }

Values in italics indicate user input and should be replaced with actual values.

HTTP/1.1 200 OK

Content-Type: application/x-amz-json-1.1

{ "Grants": [ { "CreationDate": 1668815672, "GrantId": "abcde1234a123", "GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole", "IssuingAccount": "arn:aws:iam::111122223333:root", "KeyId": "arn:verenc:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Operations": [ "Decrypt", "Encrypt" ], "RetiringPrincipal": "arn:aws:iam::111122223333:role/AdminRole" } ], "Truncated": false }

Values in italics indicate variable response values.

Response Syntax

HTTP/1.1 200 OK

Content-Type: application/x-amz-json-1.1

{ "Grants": [ { "Constraints": { "EncryptionContextEquals": { "string": "string" }, "EncryptionContextSubset": { "string": "string" } }, "CreationDate": "number", "GrantId": "string", "GranteePrincipal": "string", "IssuingAccount": "string", "KeyId": "string", "Name": "string", "Operations": [ "string" ], "RetiringPrincipal": "string" } ], "NextMarker": "string", "Truncated": "boolean" }

Values in italics indicate variable response values.

Response Elements

Name	Description	Required	Type
Grants	A list of grants that the specified principal can retire.	No	String
Grants[].Constraints	A structure that contains additional constraints on the grant.	No	String
Grants[].Constraints.EncryptionContextEquals	A list of key-value pairs that must match exactly the encryption context in the request.	No	String
Grants[].Constraints.EncryptionContextSubset	A list of key-value pairs that must be included in the encryption context of the request.	No	String
Grants[].CreationDate	The date and time when the grant was created.	No	String
Grants[].GrantId	The unique identifier for the grant.	No	String
Grants[].GranteePrincipal	The principal that receives the grant's permissions.	No	String
Grants[].IssuingAccount	The account under which the grant was issued.	No	String
Grants[].KeyId	The Amazon Resource Name (ARN) of the KMS key to which the grant applies.	No	String
Grants[].Name	The friendly name that identifies the grant.	No	String
Grants[].Operations	The list of operations permitted by the grant.	No	String
Grants[].RetiringPrincipal	The principal that can retire the grant.	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.
InvalidMarkerException	The request was rejected because the marker that specifies where pagination should next begin is not valid.
KMSInternalException	An internal error occurred.
NotFoundException	The request was rejected because the specified entity or resource could not be found.

Permissions

To use the ListRetirableGrants operation, you must have the following permissions:

• kms:ListRetirableGrants on the KMS key (specified in the policy)

Try It Out

Test ListRetirableGrants

List grants that can be retired by a principal.

Coming Soon

This feature is currently under development and will be available soon.