--- name: hs-crypto-rotate-keys title: Rotating root keys manually description: You can rotate your root keys on demand by using IBM Cloud® Hyper Protect Crypto Services. last-updated: 2026-07-01 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/hs-crypto?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Rotating root keys manually {: #rotate-keys} IBM Cloud® Hyper Protect Crypto Services is deprecated. As of 28 March 2026, you can't create new instances, and access to free instances will be removed. Existing premium plan instances are supported until 28 March 2027. Any instances that still exist on that date will be deleted. {: deprecated} You can rotate your [root keys](#x6946961){: term} on demand by using IBM Cloud® Hyper Protect Crypto Services. {: shortdesc} When you rotate your root key, you shorten the lifetime of the key, and you limit the amount of information that is protected by that key. To learn how key rotation helps you meet industry standards and cryptographic best practices, see [Key rotation](https://cloud.ibm.com/docs/hs-crypto/concepts?topic=hs-crypto-root-key-rotation-intro&format=markdown). ## Rotating root keys in the UI {: #rotate-root-key-gui} {: help} {: support} {: ui} If you prefer to rotate your root keys by using a graphical interface, you can use the UI. [After you create or import your existing root keys into the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-root-keys&format=markdown), complete the following steps to rotate a key: 1. [Log in to the UI](https://cloud.ibm.com/login){: external}. 2. Go to **Menu** > **Resource list** to view a list of your resources. 3. From your IBM Cloud resource list, select your provisioned instance of Hyper Protect Crypto Services. 4. On the **KMS keys** page, use the **Keys** table to browse the keys in your service. 5. Select the key that you want to rotate and click the **Actions** icon ![Actions icon](../icons/action-menu-icon.svg "Actions") to open a list of options for the key. 6. From the options menu, click **Rotate key**. If you initially provided the key material for the key, specify the new base64 encoded key material that you want to store and manage in the service. Ensure that the key material meets the following requirements: - Must be 128, 192, or 256 bits. - The bytes of data, for example 32 bytes for 256 bits, must be encoded by using base64 encoding. 7. Click **Rotate key** to confirm. ## Rotating root keys with the API {: #rotate-root-key-api} {: api} You can rotate a root key by making a `POST` call to the following endpoint. ``` https://.api..hs-crypto.appdomain.cloud/api/v2/keys//actions/rotate ``` {: codeblock} 1. [Retrieve your service and authentication credentials to work with keys in the service.](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api&format=markdown) 2. Copy the ID of the root key that you want to rotate. You can find the ID for a key in your service instance by [retrieving a list of your keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-keys&format=markdown), or by accessing the UI. 3. Replace the key with new key material by running the following cURL command. ```sh curl -X POST \ 'https://.api..hs-crypto.appdomain.cloud/api/v2/keys//actions/rotate' \ -H 'accept: application/vnd.ibm.kms.key_action+json' \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' \ -H "x-kms-key-ring: " \ -H 'content-type: application/vnd.ibm.kms.key_action+json' \ -d '{ "payload": "" }' ``` {: codeblock} Replace the variables in the example request according to the following table. | Variable | Description | | --- | --- | | `region` | **Required.** The region abbreviation, such as `us-south` or `au-syd`, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions&format=markdown#service-endpoints). | | `port` | **Required.** The port number of the API endpoint. | | `key_ID` | **Required.** The unique identifier for the root key that you want to rotate. | | `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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token&format=markdown). | | `instance_ID` | **Required.** The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID&format=markdown). | | `key_ring_ID` | **Optional.** The unique identifier of the key ring that the key belongs to. If unspecified, Hyper Protect Crypto Services will search for the key in every key ring that is associated with the specified instance. Therefore, it is suggested to specify the key ring ID for a more optimized request. \n \n Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is: default. For more information, see [Managing key rings](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-key-rings&format=markdown). | | `key_material` | **Optional.** The new base64 encoded key material that you want to store and manage in the service. This value is required if you initially imported the key material when you added the key to the service. \n \n To rotate a key that was initially generated by Hyper Protect Crypto Services, omit the `payload` attribute and pass an empty request entity-body. To rotate an imported key, provide a key material that meets the following requirements: \n * The key must be 128, 192, or 256 bits. \n * The bytes of data, for example 32 bytes for 256 bits, must be encoded by using base64 encoding. | {: caption="Describes the variables needed to rotate a specified key in Hyper Protect Crypto Services" caption-side="bottom"} A successful rotation request returns an HTTP `204 No Content` response, which indicates that your root key was replaced by new key material. 4. Optional: Verify that the key was rotated by running the following call to browse the keys in your Hyper Protect Crypto Services service instance. ```cURL curl -X GET \ https://.api..hs-crypto.appdomain.cloud/api/v2/keys \ -H 'accept: application/vnd.ibm.collection+json' \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' \ ``` {: codeblock} Review the `lastRotateDate` value in the response entity-body to inspect the date and time that your key was last rotated. ```json { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "02fd6835-6001-4482-a892-13bd2085f75d", "name": "test-root-key", "state": 1, "extractable": false, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d", "imported": false, "creationDate": "2020-03-12T03:50:12Z", "createdBy": "...", "algorithmType": "AES", "algorithmMetadata": { "bitLength": "256", "mode": "CBC_PAD" }, "algorithmBitSize": 256, "algorithmMode": "CBC_PAD", "lastUpdateDate": "2020-03-12T03:50:12Z", "lastRotateDate": "2020-03-12T03:49:01Z", "keyVersion": { "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2", "creationDate": "2020-03-12T03:50:12Z" }, "dualAuthDelete": { "enabled": false }, "deleted": false } ] } ``` {: screen} The `keyVersion` attribute contains identifying information that describes the latest version of the root key. You can also list the versions that are available for the key by using the Hyper Protect Crypto Services key management service API. To learn more, see [Viewing key versions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-key-versions&format=markdown). {: tip} ### Using an import token to rotate a key {: #rotate-root-keys-secure-api} If you initially imported a root key by using an import token, you can rotate the key by making a `POST` call to the following endpoint. ``` https://.api..hs-crypto.appdomain.cloud/api/v2/keys//actions/rotate ``` 1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api&format=markdown). To rotate a key, you must be assigned a _Writer_ or _Manager_ access policy for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out [Service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-access&format=markdown#service-access-roles). {: note} 2. Retrieve the ID of the key that you want to rotate. You can retrieve the ID for a specified key by making a `GET /v2/keys` request, or by viewing your keys in the UI. 3. [Create and retrieve an import token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-import-tokens&format=markdown). 4. Use the import token to encrypt the key material that you want to use to rotate the existing key. To learn how to use an import token, check out [Tutorial: Creating and importing encryption keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tutorial-import-keys&format=markdown). 5. Replace the existing key with new key material by running the following cURL command. ```cURL curl -X POST \ https://.api..hs-crypto.appdomain.cloud/api/v2/keys//actions/rotate \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' \ -H 'accept: application/vnd.ibm.kms.key_action+json' \ -H 'content-type: application/vnd.ibm.kms.key_action+json' \ -d '{ "type": "application/vnd.ibm.kms.key+json", "name": "", "description": "", "extractable": , "payload": "", "encryptionAlgorithm": "RSAES_OAEP_SHA_1", "encryptedNonce": "", "iv": "" }' ``` {: codeblock} Replace the variables in the example request according to the following table. | Variable | Description | | --- | --- | | `region` | **Required.** The region abbreviation, such as `us-south` or `au-syd`, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions&format=markdown#service-endpoints). | | `port` | **Required.** The port number of the API endpoint. | | `key_ID` | **Required.** The unique identifier for the key that you want to rotate. | | `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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token&format=markdown). | | `instance_ID` | **Required.** The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID&format=markdown). | | `key_alias` | **Required.** A unique, human-readable name for easy identification of your key. To protect your privacy, do not store your personal data as metadata for your key. | | `key_description` | An extended description of your key. To protect your privacy, do not store your personal data as metadata for your key. | | `encrypted_key` | **Required.** The new key material that is encrypted by the import token. The value must be base64 encoded. Ensure that the key material meets the following requirements: \n * The key must be 128, 192, or 256 bits. \n * The bytes of data, for example 32 bytes for 256 bits, must be encoded by using base64 encoding. \n \n To learn more, see [Tutorial: Creating and importing encryption keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tutorial-import-keys&format=markdown#tutorial-import-encrypt-key). | | `key_type` | A boolean value that determines whether the key material can leave the service. When you set the `extractable` attribute to `false`, the service designates the key as a root key that you can use for `wrap` or `unwrap` operations. | | `encrypted_nonce` | **Required.** The AES-GCM encrypted nonce that ensures that the bits you send as part of a request are exactly the same as what we receive. The nonce validates the key that you are restoring. To learn more, see [Tutorial: Creating and importing encryption keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tutorial-import-keys&format=markdown#tutorial-import-encrypt-nonce). | | `iv` | **Required.** The initialization vector (IV) that is generated by the AES-GCM algorithm when you encrypt a nonce. This value is used to decode the key for storage in the Hyper Protect Crypto Services system. To learn more, see [Tutorial: Creating and importing encryption keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tutorial-import-keys&format=markdown#tutorial-import-encrypt-nonce). | {: caption="Describes the variables needed to restore keys with thHyper Protect Crypto Services API" caption-side="bottom"} A successful rotation request returns an HTTP `204 No Content` response, which indicates that your root key was replaced by the new key material. 6. Optional: Verify that the key was rotated by retrieving details about the key. ```cURL curl -X GET \ https://.api..hs-crypto.appdomain.cloud/api/v2/keys//metadata \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' -H 'accept: application/vnd.ibm.kms.key+json' ``` {: codeblock} Review the `lastRotateDate` and `keyVersion` values in the response entity-body to inspect the date and time that your key was last rotated. You can also list the versions that are available for the key by using the Hyper Protect Crypto Services API. To learn more, see [Viewing key versions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-key-versions&format=markdown). ## What's next {: #rotate-key-next} - After you rotate a root key, new cryptographic key material becomes available for protecting the data encryption keys (DEKs) that are associated with the root key. Learn how to reencrypt or rewrap your DEKS without exposing the keys in their plain text form, see [Rewrapping keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rewrap-keys&format=markdown). - To learn how envelope encryption helps you control the security of at-rest data in the cloud, see [Protecting data with envelope encryption](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-envelope-encryption&format=markdown). - To find out more about programmatically managing your keys, [check out the Hyper Protect Crypto Services key management service API reference doc](https://cloud.ibm.com/apidocs/hs-crypto){: external}.