To delete a grant, retire or revoke it.
The RetireGrant and RevokeGrant operations are very similar to each other. Both operations delete a grant, which eliminates the permissions the grant allows. The primary difference between these operations is how they are authorized.
- RevokeGrant
-
Like most AWS KMS operations, access to the
RevokeGrant
operation is controlled through key policies and IAM policies. The RevokeGrant API can be called by any principal withkms:RevokeGrant
permission. This permission is included in the standard permissions given to key administrators. Typically, administrators revoke a grant to deny permissions the grant allows. - RetireGrant
-
The grant determines who can retire it. This design allows you to control the lifecycle of a grant without changing key policies or IAM policies. Typically, you retire a grant when you are done using its permissions.
A grant can be retired by an optional retiring principal specified in the grant. The grantee principal can also retire the grant, but only if they are also a retiring principal or the grant includes the
RetireGrant
operation. As a backup, the AWS account in which the grant was created can retire the grant.There is a
kms:RetireGrant
permission that can be used in IAM policies, but it has limited utility. Principals specified in the grant can retire a grant without thekms:RetireGrant
permission. Thekms:RetireGrant
permission alone does not allow principals to retire a grant. Thekms:RetireGrant
permission is not effective in a key policy or resource control policy.-
To deny permission to retire a grant, you can use a
Deny
action with thekms:RetireGrant
permission in your IAM policies. -
The AWS account that owns the KMS key can delegate the
kms:RetireGrant
permission to an IAM principal in the account. -
If the retiring principal is a different AWS account, administrators in the other account can use
kms:RetireGrant
to delegate permission to retire the grant to an IAM principal in that account.
-
The AWS KMS API follows an eventual consistency model. When you create, retire, or revoke a grant, there might be a brief delay before the change is available throughout AWS KMS. It typically takes less than a few seconds for the change to propagate throughout the system, but in some cases it can take several minutes. If you need to delete a new grant immediately, before it is available throughout AWS KMS, use a grant token to retire the grant. You cannot use a grant token to revoke a grant.