Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

GetKeyLastUsage

Returns usage information about the last successful cryptographic operation performed with a specified KMS key, including the operation type, timestamp, and associated AWS CloudTrail event ID.

The TrackingStartDate in the GetKeyLastUsage response indicates the date from which AWS KMS began recording cryptographic activity for a given key. Use this value together with KeyCreationDate to understand the key's usage history:

If the KeyLastUsage response element is present, the key has been used for a successful cryptographic operation since the TrackingStartDate. The response includes the operation type, timestamp, and associated CloudTrail event ID.
If the KeyLastUsage response element is empty and KeyCreationDate is on or after TrackingStartDate, the key has not been used for a successful cryptographic operation since it was created.
If the KeyLastUsage response element is empty and KeyCreationDate is before TrackingStartDate, there is no record of the key being used for a successful cryptographic operation since the TrackingStartDate. However, the key may have been used before tracking began. To determine whether the key was used before the TrackingStartDate, examine your past AWS CloudTrail logs.

For multi-Region KMS keys, primary and replica keys track last usage independently. Each key in a multi-Region key set maintains its own usage information.

The ReEncrypt operation uses two keys: a source key for decryption and a destination key for encryption. Usage information is recorded for both keys independently, each with the AWS CloudTrail event ID from the respective key owner's account.

Note

Do not use GetKeyLastUsage as the sole indicator when scheduling a key for deletion. Instead, first disable the key and monitor AWS CloudTrail for DisabledException entries, as there could be infrequent workflows that are dependent on the key. By looking for this exception, you can identify potential dependencies and workload failures before they occur.

Cross-account use: No. You cannot perform this operation on a KMS key in a different AWS account.

Required permissions: kms:GetKeyLastUsage (key policy)

Related operations:

Eventual consistency: The AWS KMS API follows an eventual consistency model. For more information, see AWS KMS eventual consistency.

Request Syntax


{
   "KeyId": "string"
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

KeyId

Identifies the KMS key to get usage information for. To specify a KMS key, use its key ID or key ARN. Alias names are not supported.

Specify the key ID or key ARN of the KMS key.

For example:

Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Response Syntax


{
   "KeyCreationDate": number,
   "KeyId": "string",
   "KeyLastUsage": { 
      "CloudTrailEventId": "string",
      "KmsRequestId": "string",
      "Operation": "string",
      "Timestamp": number
   },
   "TrackingStartDate": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

KeyCreationDate

The date and time when the KMS key was created.

Type: Timestamp

KeyId

The globally unique identifier for the KMS key.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

KeyLastUsage

Contains usage information about the last time the KMS key was used for a successful cryptographic operation. If the key has not been used since tracking began, this response element is empty.

Type: KeyLastUsageData object

TrackingStartDate

The date from which AWS KMS began recording cryptographic activity for this key, or the date the KMS key was created, whichever is later.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Error Types.

DependencyTimeoutException

The system timed out while trying to fulfill the request. You can retry the request.

HTTP Status Code: 500

InvalidArnException

The request was rejected because a specified ARN, or an ARN in a key policy, is not valid.

HTTP Status Code: 400

KMSInternalException

The request was rejected because an internal exception occurred. The request can be retried.

HTTP Status Code: 500

NotFoundException

The request was rejected because the specified entity or resource could not be found.

HTTP Status Code: 400