--- title: "Encryption Key Rotation" slug: "encryption-key-rotation" tags: ["Data Encryption", "Encryption Keys", "EncryptedOrPIIField"] updated: 2026-02-04T16:40:54Z published: 2026-02-04T16:40:54Z --- > ## Documentation Index > Fetch the complete documentation index at: https://documentation.decisions.com/llms.txt > Use this file to discover all available pages before exploring further. # Encryption Key Rotation | Feature | | --- | | **Introduced in Version** | 6.8.0 | | **Last Modified in Version** | 9.14.0 | | **Location** | **System > Administration > Encryption** | ## Overview In an effort to support PCI and SOC compliance, data stored within Decisions can be encrypted using a rotating encryption key. This prevents data from being compromised if a key is lost or stolen. **How key rotation works:** during rotation, Decisions attempts to **decrypt existing encrypted values using the current key** and then **re-encrypts those values using a new key**. If any value cannot be decrypted (for example, because it is already corrupted/invalid), rotation cannot proceed until the issue is resolved. Important: Run Test Default Key Rotation firstUsers should not manually modify encryption keys or encrypted values in the database. Key rotation must be performed through the provided dashboard actions. Before running an actual rotation, run **Test Default Key Rotation** to confirm the environment is eligible and to identify any blocking issues. --- ## Accessing Key Rotation To view the Key Rotation History, navigate to **System > Administration > Encryption.**The Key Rotation Audit dashboard will appear, displaying the rotation history. ![](https://cdn.document360.io/6ef8bcc1-6489-4486-9ad1-83acff7e5df0/Images/Documentation/2024-08-12_15h00_35.png) --- ## Before you begin - Run key rotation during a **maintenance window**. - Take a **backup of the Decisions database** before rotating keys. - Take a backup of **Keys.dat** before rotating keys. --- ## What is unaffected/unchanged by Key Rotation? Cached data will not be affected by rotating Encryption Keys. In addition, data that cannot be updated/decrypted during this process will: - Become a task assigned to the admin group for review. - Be recorded in an `encryption_key_change_issue`table within the Decisions database with the following columns: - Source datatype Table - Source datatype ID - Field Name - Data - Date Time - Current Key --- ## Changing Keys Upgrade Data EncryptionAll data in the database must be upgraded to support key rotation. This process can be initialized using the **Start Upgrade to Support Encryption** action. Data cannot be encrypted until this action has been completed. To rotate encryption keys: 1. Select **Test Default Key Rotation** on the Key Rotation Audit dashboard to verify that rotation can be completed successfully.![](https://cdn.document360.io/6ef8bcc1-6489-4486-9ad1-83acff7e5df0/Images/Documentation/image-1770156308819.png) 2. If the test reports blocking issues, resolve them using the steps in [Troubleshooting Key Rotation](/docs/encryption-key-rotation#troubleshooting-key-rotation), then re-run **Test Default Key Rotation**. 3. When **Test Default Key Rotation**succeeds, select **Start Default Key Rotation**. 4. In the confirmation pop-up, confirm that the key will be rotated.![](https://cdn.document360.io/6ef8bcc1-6489-4486-9ad1-83acff7e5df0/Images/Documentation/image-1770156374504.png) If the rotation was successful, then: - The Rotation Status is set to Complete - Old keys.dat is moved to **archive/Keys.dat.MMddYYYY**folder within the Decisions folder tree. - NewKeys.dat becomes the new keys.dat file. Rotating keys for clustered environmentsFor clustered environments, the updated encryption keys will be sent to other nodes within the cluster. The action will only need to be started on the environment marked as the Job Server.  If the key rotation is unsuccessful, then the following will occur: - The status message on the Keys dashboard will be updated to **Rotation Not Available: Encryption Issues Exist**. - The Encryption Issues Report will be updated, displaying the cause for failure. - All issues must be resolved for Key rotation to continue. --- ## Troubleshooting Key Rotation If **Test Default Key Rotation** fails, it typically means some encrypted data is already in a bad state and cannot be decrypted with the current key. Because rotation requires decrypting existing values first, **all reported issues must be resolved before rotation can proceed**. ### Common failure scenario - **Encrypted configuration data is invalid or corrupted** (for example, an external database connection stored with an incorrect/invalid connection string). ### How to remediate Encryption Issues 1. Open **System > Administration > Encryption** and review the **Encryption Issues** report. 2. Identify the affected item (the report typically indicates what failed and where it is stored). 3. Navigate to the referenced configuration item (for example, the external database connection) and **re-save** it with correct values (for example, update and save the connection string/credentials). 4. Return to the Key Rotation Audit dashboard and re-run **Test Default Key Rotation**. 5. Repeat until no blocking issues remain, then run **Start Default Key Rotation**. What it means if Test Default Key Rotation failsA failed test indicates that Decisions cannot decrypt one or more existing encrypted values using the current key. This usually points to corrupted/invalid stored data that must be corrected before rotation. --- ## Dashboards The following section lists the different dashboards and reports available under **System > Administration > Encryption** Folder | Feature | Description | Screenshot | | --- | --- | --- | | Key Rotation Audit | The main dashboard that is displayed when navigating to Encryption > Key Rotation Audit. Displays a list of activities involving Key rotation. | ![](https://cdn.document360.io/6ef8bcc1-6489-4486-9ad1-83acff7e5df0/Images/Documentation/image-1770156041964.png) | | Keys | A Report that displays the list of active encryption keys within Decisions | ![](https://cdn.document360.io/6ef8bcc1-6489-4486-9ad1-83acff7e5df0/Images/Documentation/image-1770156103086.png) | | Encryption Issues | A Report detailing a list of encryption issues that are preventing encryption keys from being rotated. Use this report to identify the failing item and remediate it (for example, re-save an invalid encrypted connection/configuration), then re-run **Test Default Key Rotation**. | ![](https://cdn.document360.io/6ef8bcc1-6489-4486-9ad1-83acff7e5df0/Images/Documentation/image-1770156148437.png) | | Issue Resolution History | A Report detailing what actions were taken to resolve issues that had appeared when attempting to encrypt keys for the environment. | ![](https://cdn.document360.io/6ef8bcc1-6489-4486-9ad1-83acff7e5df0/Images/Documentation/image-1770156191673.png) | ### Status The following section lists common status messages for the encryption process. | Status | Description | | --- | --- | | Key Rotation is Available | This status means that key rotation is available and can be run. We recommend that this be done during a maintenance window. | | Rotation Not Available: Encryption Issues Exist | There are issues with encrypted data, or a previous key rotation appears to be in progress. This will prevent the encryption keys from being rotated until all issues are resolved. | | Complete | The encryption key has been successfully rotated. No further actions are necessary. | --- ## Types of Key Rotation Users in v9.5 and higher have access to two kinds of key rotation: **ORM** and **Default**. ORM rotation applies to keys tied to Data Structures. Default rotation is for any keys that are associated with system-wide data, such as connection strings, SMTP settings, or passwords. After performing a Default Key Rotation, a pop-up message will appear, indicating that the Decisions service must be restarted to clear the cache. **Restarting the service is recommended after key rotation to avoid potential issues.** --- ## Feature Changes | Description | Version | Release Date | Developer Task | | --- | --- | --- | --- | | Added Default Key Rotation | [9.5](https://documentation.decisions.com/v99/docs/version-95x-release-notes) | November 2024 | [DT-042772] | | After performing a Default Key Rotation, a pop-up message appears indicating that the Decisions service needs to be restarted to clear the cache. | [9.14](https://documentation.decisions.com/v99/docs/version-914x-release-notes?highlight=DT-044689) | August 2025 | [DT-044689] |