delete-keys.md

copyright	lastupdated	Keywords	subcollection
years 2018, 2019	2019-03-13	details of the DELETE request, delete encryption key, deleting keys, Variable Description region	hs-crypto

{:shortdesc: .shortdesc} {:codeblock: .codeblock} {:screen: .screen} {:new_window: target="_blank"} {:pre: .pre} {:tip: .tip}

Deleting keys

{: #deleting-keys}

You can use {{site.data.keyword.cloud}} {{site.data.keyword.hscrypto}} to delete an encryption key and its contents, if you are an admin for your {{site.data.keyword.cloud_notm}} space or {{site.data.keyword.hscrypto}} service instance. {: shortdesc}

Important: When you delete a key, you permanently shred its contents and associated data. The action cannot be reversed. Destroying resources is not recommended for production environments, but might be useful for temporary environments such as testing or QA.

Deleting keys with the GUI

{: #delete-keys-gui}

If you prefer to delete your encryption keys by using a graphical interface, you can use the {{site.data.keyword.hscrypto}} GUI.

After you create or import your existing keys into the service, complete the following steps to delete a key:

1. Log in to the {{site.data.keyword.cloud_notm}} console {: new_window}.
2. Go to Menu > Resource List to view a list of your resources.
3. From your {{site.data.keyword.cloud_notm}} resource list, select your provisioned instance of {{site.data.keyword.hscrypto}}.
4. Use the Keys table to browse the keys in your service.
5. Click the ⋮ icon to open a list of options for the key that you want to delete.
6. From the options menu, click Delete key and confirm the key deletion in the next screen.

After you delete a key, the key transitions to the Destroyed state. Keys in this state are no longer recoverable. Metadata that is associated with the key, such as the key's deletion date, is kept in the {{site.data.keyword.hscrypto}} database.

Deleting keys with the API

{: #api}

To delete a key and its contents, make a DELETE call to the following endpoint.

https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>

1. Retrieve your service and authentication credentials to work with keys in the service.

2. Retrieve the ID of the key that you would like to delete.

   You can retrieve the ID for a specified key by making a GET /v2/keys/ request, or by viewing your keys in the {{site.data.keyword.hscrypto}} dashboard.

3. Run the following cURL command to permanently delete the key and its contents.

   curl -X DELETE \
     https://<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID> \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'prefer: <return_preference>'
   

   {: codeblock}

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

   Table 1. Describes the variables that are needed to delete keys with the {{site.data.keyword.hscrypto}} API.

   Variable	Description
   region	The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your {{site.data.keyword.hscrypto}} service instance resides. For more information, see Regional service endpoints.
   key_ID	The unique identifier for the key that you would like to delete.
   IAM_token	Your {{site.data.keyword.cloud_notm}} 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	The unique identifier that is assigned to your {{site.data.keyword.hscrypto}} service instance. For more information, see Retrieving an instance ID.
   return_preference	A header that alters server behavior for POST and DELETE operations. When you set the return_preference variable to return=minimal, the service returns a successful deletion response. When you set the variable to return=representation, the service returns both the key material and the key metadata.

   If the return_preference variable is set to return=representation, the details of the DELETE request are returned in the response entity-body. The following JSON object shows an example returned value.

   {
     "metadata": {
       "collectionType": "application/vnd.ibm.kms.key+json",
       "collectionTotal": 1
     },
     "resources": [
       {
         "id": "...",
         "type": "application/vnd.ibm.kms.key+json",
         "name": "...",
         "description": "...",
         "state": 5,
         "crn": "...",
         "deleted": true,
         "algorithmType": "AES",
         "createdBy": "...",
         "deletedBy": "...",
         "creationDate": "YYYY-MM-DDTHH:MM:SS.SSZ",
         "deletionDate": "YYYY-MM-DDTHH:MM:SS.SSZ",
         "lastUpdateDate": "YYYY-MM-DDTHH:MM:SS.SSZ",
         "nonactiveStateReason": 2,
         "extractable": true
       }
     ]
   }
   

   {: screen}

   For a detailed description of the available parameters, see the {{site.data.keyword.hscrypto}} REST API reference doc {: new_window}.