About deleting and purging keys

You can use IBM® Key Protect for IBM Cloud® to delete an encryption key and its key material if you are a manager for your Key Protect instance.

Before you can delete an instance, you must delete every key in that instance. However, if you close your account, any existing instances and keys are automatically hard deleted. Check out Account cancelation and data deletion for more information.

In the event that a key is no longer needed or should be removed, Key Protect allows you to delete and ultimately purge keys, an action that shreds the key material and makes any of the data encrypted with it inaccessible.

Deleting a key moves it into a Destroyed state, a "soft" deletion in which the key can still be seen and restored for 30 days. After 90 days, the key will be automatically purged, or "hard deleted", and its associated data will be permanently shredded and removed from the Key Protect service. If it is desirable that a key be purged sooner than 90 days, it is also possible to hard delete a key four hours after it has been moved into the Destroyed state.

After a key has been deleted, any data that is encrypted by the key becomes inaccessible, though this can be reversed if the key is restored within the 30-day time frame. After 30 days, key metadata, registrations, and policies are available for up to 90 days, at which point the key becomes eligible to be purged. Note that once a key is no longer restorable and has been purged, its associated data can no longer be accessed. As a result, destroying resources is not recommended for production environments unless absolutely necessary.

The following table lists the time frames in which you can view, restore, and purge a key after it has been deleted.

Lists how users can interact with keys during certain time intervals after a key has been deleted
Time from key deletion	Name of key state	Can view/access key data?	Can restore?	Can user initiate purge?
One second - Four hours	Destroyed	Yes	Yes	No
4 hours - 30 days	Destroyed	Yes	Yes	Yes
30-90 days	Destroyed	Yes	No	Yes
After 90 days	Purged `*`	No	No	Yes

* Note: because purged keys are completely inaccessible and "destroyed" in the common usage of the word, there is technically no "purged" key state. Purged keys no longer exist and therefore don't have a "state" one way or another. However, it can be useful to think of "purged" as being a state as nonexistence is part of the lifecycle of a key.

Once a key has been purged, any API calls that use the Key ID of a purged key will result in a 404 HTTP Not Found error. If you are required to retain any data related to a purged key (key metadata, registrations, policies, etc) for an extended period of time, it is recommended to perform the necessary API or CLI calls to retrieve and store that data in your own storage device.

Considerations before deleting and purging a key

Key Protect blocks the deletion of any key that's actively protecting any registered cloud resources. Before you delete a key:

Review the registered IBM Cloud resources that are associated with the key. If needed, you can force deletion on a key that's protecting a registered cloud resource. However, the action won't succeed if the key's associated resource is non-erasable due to a retention policy, which is a Write Once Read Many (WORM) policy set on the customer's relevant cloud resource.
Verify whether a key has a retention policy by checking the preventKeyDeletion field of the registration details for the key. Then, you must contact IBM Cloud support to remove the retention policy on each resource that is associated with the key before you can delete the key.
Verify the key's deletion authorization policy. By default, keys in Key Protect only require a single deletion authorization by a user with the Manager role However, if a dual authorization policy has been set, two users with the Manager role will have to approve the deletion.

Key Protect restricts the ability to purge keys after only four hours to users with the KeyPurge role, which must be specifically set for a user as it is not enabled by default, even for the instance owner. This ability is restricted precisely because purged keys cannot be restored. If there is any doubt whether a key should be purged four hours after it has been deleted, do not purge it.

API Example

Please refer to the prerequisites and configuration settings associated with the API reference, before using this example.

curl -X DELETE
    https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/purge
    -H 'accept: application/vnd.ibm.kms.key+json'
    -H 'authorization: Bearer <IAM_token>'
    -H 'bluemix-instance: <instance_ID>'

Replace the variables in the example request according to the following table.

Describes the variables that are needed to purge a key with the Key Protect API.
Variable	Description
region	Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
keyID_or_alias	Required. The unique identifier or alias for the key that you would like to purge.
IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.

For a detailed description of the request, see the Key Protect REST API reference doc.

What's next

To learn how to delete and purge a key using the UI, check out Deleting keys using a single authorization. For information about how to do this using the API, click the API tab at the beginning of the topic.

To learn how to delete and purge a key that holds a dual-authorization deletion policy using the UI, check out Deleting keys using dual authorization. For information about how to do this using the API, click the API tab at the beginning of the topic.