--- name: key-protect-rotate-keys title: Manually rotating keys description: You can rotate your root keys manually by using IBM® Key Protect for IBM Cloud®. last-updated: 2026-06-24 --- # Manually rotating keys {: #rotate-keys} You can rotate your root keys manually by using IBM® Key Protect for IBM Cloud®. {: shortdesc} When you rotate your root key, you add new key material to the key. This process creates a new key version that you can use for [rewrapping or reencrypting your data](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rewrap-keys). To learn how key rotation helps you meet industry standards and cryptographic best practices, see [Rotating your encryption keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-rotation). Rotation is available only for root keys. To learn more about your key rotation options in Key Protect, check out [Comparing your key rotation options](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-rotation#compare-key-rotation-options). {: note} ## Rotating root keys in the console {: #rotate-key-gui} {: ui} [After you create a root key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-root-keys), complete the following steps to rotate the key: 1. [Log in to the IBM Cloud console](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 Key Protect. 4. On the application details page, use the **Keys** table to browse the keys in your service. If you have many keys, use the search bars to filter for enabled keys (since other kinds of keys cannot be rotated), keys in a particular key ring, and keys with a particular alias. 5. Once the key has been found, click the **Actions** icon (⋯) to open a list of options for the key that you want to rotate. 6. From the options menu, click **Rotate** to open the **Rotate** side panel. 7. From here, you can rotate the key one time by clicking **Rotate**. If this key was imported, you must provide new key material. You can also set a rotation policy for this key on an interval of your choosing: - Go back to key options and click **Edit rotation policy** - **Enable** the policy - Select the 30-day interval for key rotation you want If a key is set to be rotated every `2` months, for example, it will be rotated every 60 days, regardless of the number of days in a particular month. 8. Click **Save** to establish this policy. To learn about setting a rotation policy for your instance that sets a rotation policy on every subsequently created key, check out [Setting a rotation policy](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-rotation-policy). **For imported root keys only**, you must add base64 encoded key material that you want to store and manage in the service. Ensure that the key material is in 128, 192, or 256 bits and that the bytes of data (for example, 32 bytes for 256 bits) are encoded by using base64 encoding. {: important} ## Rotating root keys with the API {: #rotate-key-api} {: api} You can rotate a root key by making a `POST` call to the following endpoint. ```plaintext https://.kms.cloud.ibm.com/api/v2/keys//actions/rotate ``` {: codeblock} 1. [Retrieve authentication credentials to work with keys in the service.](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api) 2. Copy the ID of the root key that you want to rotate. You can find the ID for a key in your Key Protect instance by [retrieving a list of your keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys), or by accessing the Key Protect dashboard. 3. Rotate the key by providing new key material with the following `curl` command. ```sh $ curl -X POST \ "https://.kms.cloud.ibm.com/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 `eu-gb`, that represents the geographic area where your Key Protect instance resides.

For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions#service-endpoints).| |keyID_or_alias|**Required**. The unique identifier or alias 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/key-protect?topic=key-protect-retrieve-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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID).| |key_ring_ID|**Optional**. The unique identifier of the key ring that the key is a part of. If unspecified, Key Protect will search for the key in every key ring associated with the specified instance. It is recommended to specify the key ring ID for a more optimized request.

Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is: default.

For more information, see [Grouping keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grouping-keys).| |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.

To rotate a key that was initially generated by Key Protect, 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:

The key 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.| {: caption="Variables for rotating a key" 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. ### Optional: Verify key rotation {: #rotate-key-api-verify} {: api} You can verify that a key has been rotated by issuing a list keys request: ```sh $ curl -X GET \ "https://.kms.cloud.ibm.com/api/v2/keys" \ -H "accept: application/vnd.ibm.collection+json" \ -H "authorization: Bearer " \ -H "bluemix-instance: " ``` {: codeblock} Where the `` is the name of your instance and your `` is your IAM token. Review the `lastRotateDate` and `keyVersion` values 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:kms: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": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "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 Key Protect API. To learn more, see [Viewing key versions](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-key-versions). {: tip} ### Using an import token to rotate a key {: #rotate-keys-secure-api} {: 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. ```plaintext https://.kms.cloud.ibm.com/api/v2/keys//actions/rotate ``` {: codeblock} 1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api). 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 Key Protect service actions, check out [Service access roles](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-access#manage-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 Key Protect dashboard. 3. [Create and retrieve an import token](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-import-tokens). 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/key-protect?topic=key-protect-tutorial-import-keys). 5. Replace the existing key with new key material by running the following `curl` command. ```sh $ curl -X POST \ "https://.kms.cloud.ibm.com/api/v2/keys//actions/rotate" \ -H "authorization: Bearer " \ -H "bluemix-instance: " \ -d '{ "type": "application/vnd.ibm.kms.key+json", "name": "", "description": "", "extractable": , "payload": "", "encryptionAlgorithm": "RSAES_OAEP_SHA_256", "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 `eu-gb`, that represents the geographic area where your Key Protect instance resides.

For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions#service-endpoints).| |keyID_or_alias|**Required**. The unique identifier or alias 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/key-protect?topic=key-protect-retrieve-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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID).| |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|**Optional**. 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 encrypted key material that you want to store and manage in the service. The value must be base64 encoded. Ensure that the key material meets the following requirements:

The key 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.| |key_type|**Optional**. A boolean value that determines whether the key material can leave the service.

When you set the extractable attribute to false, the key becomes 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/key-protect?topic=key-protect-tutorial-import-keys#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 Key Protect system.

To learn more, see [Tutorial: Creating and importing encryption keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-tutorial-import-keys#tutorial-import-encrypt-nonce).| {: caption="Variables for rotating a key with an import token" 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. ### Optional: Verify import token key rotation {: #import-token-key-rotate-api-verify} {: api} You can verify that a key that was imported via import token has been rotated by issuing a get key metadata request: ```sh $ curl -X GET \ "https://.kms.cloud.ibm.com/api/v2/keys//metadata" \ -H "accept: application/vnd.ibm.kms.key+json" \ -H "authorization: Bearer " \ -H "bluemix-instance: " ``` {: codeblock} Where the `` is the ID or alias of the key, the `` is the name of your instance, and your `` is your IAM token. 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 Key Protect API. To learn more, see [Viewing key versions](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-key-versions). {: tip}