list_retirable_grants¶
Operation¶
list_retirable_grants
async
¶
list_retirable_grants(request: ListRetirableGrantsInput | ListRetirableGrantsInputDict, /, *, plugins: list[Plugin] | None = None) -> ListRetirableGrantsOutput
list_retirable_grants(*, plugins: list[Plugin] | None = None, **kwargs: Unpack[ListRetirableGrantsInputDict]) -> ListRetirableGrantsOutput
Returns information about all grants in the Amazon Web Services account and Region that have the specified retiring principal or retiring service principal.
You can specify any principal in your Amazon Web Services account. The grants that are returned include grants for KMS keys in your Amazon Web Services account and other Amazon Web Services accounts. You might use this operation to determine which grants you may retire. To retire a grant, use the RetireGrant operation.
For detailed information about grants, including grant terminology, see Grants in KMS in the Key Management Service Developer Guide . For examples of creating grants in several programming languages, see Use CreateGrant with an Amazon Web Services SDK or CLI.
Cross-account use: You must specify a principal in your Amazon Web
Services account. This operation returns a list of grants where the
retiring principal specified in the ListRetirableGrants request is the
same retiring principal on the grant. This can include grants on KMS
keys owned by other Amazon Web Services accounts, but you do not need
kms:ListRetirableGrants permission (or any other additional
permission) in any Amazon Web Services account other than your own.
Required permissions: kms:ListRetirableGrants (IAM policy) in your Amazon Web Services account.
Note
When listing retirable grants by RetiringPrincipal, KMS authorizes
ListRetirableGrants requests by evaluating the caller account's
kms:ListRetirableGrants permissions. The authorized resource in
ListRetirableGrants calls is the retiring principal specified in the
request. KMS does not evaluate the caller's permissions to verify their
access to any KMS keys or grants that might be returned by the
ListRetirableGrants call.
The RetiringServicePrincipal filter is only usable by callers in a
service principal.
Related operations:
-
CreateGrant
-
ListGrants
-
RetireGrant
-
RevokeGrant
Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
plugins
|
list[Plugin] | None
|
A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations. |
None
|
Returns:
| Type | Description |
|---|---|
ListRetirableGrantsOutput
|
An instance of |
Input¶
Pass the input fields as keyword arguments, or pass a model or dictionary as the first positional argument. Pass plugins separately as a keyword argument.
Model¶
ListRetirableGrantsInput
dataclass
¶
Bases: _SerdeShape
Dataclass for ListRetirableGrantsInput structure.
Attributes¶
limit
class-attribute
instance-attribute
¶
limit: int | None = ...
Use this parameter to specify the maximum number of items to return. When this value is present, KMS does not return more than the specified number of items, but it might return fewer.
This value is optional. If you include a value, it must be between 1 and 100, inclusive. If you do not include a value, it defaults to 50.
marker
class-attribute
instance-attribute
¶
marker: str | None = ...
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.
retiring_principal
class-attribute
instance-attribute
¶
retiring_principal: str | None = ...
The retiring principal for which to list grants. Enter a principal in your Amazon Web Services account.
To specify the retiring principal, use the Amazon Resource Name (ARN) of an Amazon Web Services principal. Valid principals include Amazon Web Services accounts, IAM users, IAM roles, federated users, and assumed role users. For help with the ARN syntax for a principal, see IAM ARNs in the Identity and Access Management User Guide .
You must specify either RetiringPrincipal or
RetiringServicePrincipal, but not both.
retiring_service_principal
class-attribute
instance-attribute
¶
retiring_service_principal: str | None = ...
The retiring service principal for which to list grants. This filter is only usable by callers in a service principal.
You must specify either RetiringPrincipal or
RetiringServicePrincipal, but not both.
Dictionaries¶
ListRetirableGrantsInputDict
¶
Bases: TypedDict
Dictionary form of ListRetirableGrantsInput.
Attributes¶
limit
instance-attribute
¶
limit: int | None
Use this parameter to specify the maximum number of items to return. When this value is present, KMS does not return more than the specified number of items, but it might return fewer.
This value is optional. If you include a value, it must be between 1 and 100, inclusive. If you do not include a value, it defaults to 50.
marker
instance-attribute
¶
marker: str | None
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.
retiring_principal
instance-attribute
¶
retiring_principal: str | None
The retiring principal for which to list grants. Enter a principal in your Amazon Web Services account.
To specify the retiring principal, use the Amazon Resource Name (ARN) of an Amazon Web Services principal. Valid principals include Amazon Web Services accounts, IAM users, IAM roles, federated users, and assumed role users. For help with the ARN syntax for a principal, see IAM ARNs in the Identity and Access Management User Guide .
You must specify either RetiringPrincipal or
RetiringServicePrincipal, but not both.
Output¶
ListRetirableGrantsOutput
dataclass
¶
Bases: _SerdeShape
Dataclass for ListRetirableGrantsOutput structure.
Attributes¶
grants
class-attribute
instance-attribute
¶
grants: list[GrantListEntry] | None = ...
A list of grants.
next_marker
class-attribute
instance-attribute
¶
next_marker: str | None = ...
When Truncated is true, this element is present and contains the value
to use for the Marker parameter in a subsequent request.
response_metadata
class-attribute
instance-attribute
¶
Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.
truncated
class-attribute
instance-attribute
¶
truncated: bool = ...
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 this response to
the Marker parameter in a subsequent request.