RetireGrant
Retires a grant for a KMS key.
Description
The RetireGrant operation retires a grant. To retire a grant, you can use either the grant token or both the grant ID and a KMS key identifier. After a grant is retired, the permissions that it allowed are no longer valid.
note
- You should retire a grant when you're done using it to clean up the grant's permissions.
- You must identify the grant to retire by its grant token or by both the grant ID and the KMS key identifier.
- The operation doesn't return any output. If the request succeeds, the service sends back an HTTP 200 response with an empty HTTP body.
- Cross-account use: Yes. You can retire a grant on a KMS key in a different account.
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.RetireGrant" | Yes | string |
Request Body
| Name | Description | Required | Type |
|---|---|---|---|
| GrantToken | Identifies the grant to retire. You can use a grant token to identify a new grant even before it has achieved eventual consistency. Only one of `GrantToken` or `GrantId`/`KeyId` pair must be specified. | No | string |
| KeyId | The identifier of the KMS key associated with the grant. This can be the key ID or key ARN of the KMS key. Required when you use `GrantId`. | No | string |
| GrantId | Identifies the grant to retire. Required when you use `KeyId`. | No | string |
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.RetireGrant
{
"GrantToken": "AQpAM2RhZTk1MGMyNTk2ZmZmMzEyYWVhOWViN2I1MWM4Mzc0MWFiYjc0ZDE1ODkyNGFlNTIzODZhMzgyZjBlNDkxOAF4"
}
Values in italics indicate user input and should be replaced with actual values.
Response Elements
This operation returns no response data.
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. |
| InvalidGrantTokenException | The request was rejected because the specified grant token 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 RetireGrant operation, you must have one of the following:
- Be the retiring principal of the grant
- Be the grantee principal of the grant
- Have
kms:RetireGrantpermission on the KMS key (specified in the policy)
Try It Out
Test RetireGrant
Retire a grant for a KMS key.
Coming Soon
This feature is currently under development and will be available soon.