> This page is for Itential Platform On-Prem, version 6 (default).
> For other versions, use one of these documentation indexes:
> - 6 (default): https://docs.itential.com/itential-platform/6/llms.txt
> - 2023.2: https://docs.itential.com/itential-platform/2023-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Rotate the encryption key

> Replace the Itential Platform encryption key and re-encrypt stored secrets with the key rotation utility.

Platform 6.6.0+

Use the key rotation utility to replace the encryption key that Itential Platform uses to protect secrets. The utility decrypts the encrypted values in your database with the old key and re-encrypts them with a new key.

To migrate encrypted secrets from an earlier Platform version, instead use the [key migration utility](/itential-platform/maintain/upgrade#run-the-key-migration-utility).

## Before you begin

Before you rotate the key, complete the following tasks:

* Back up your MongoDB database. The utility modifies the database directly, so Itential recommends a backup before every rotation. If the rotation is interrupted, restore the database from your backup and run the utility again. For instructions, see [Back up MongoDB data](/itential-platform/6/configure/database/mongodb/back-up-and-restore#back-up-mongodb-data).
* Gather the following items:
  * The current encryption key.
  * The new encryption key.

## Rotate the key

> **Warning**
>
> In a high availability environment, stop all Platform instances before you rotate the key. Run the utility once, and update the configuration for every Platform instance before you start any of them.

#### Stop Platform

The utility can't run while Platform is running. For more information, see [Start, stop, and restart Platform](/itential-platform/6/maintain/start-stop-restart#stop).

```bash
sudo systemctl stop itential-platform
```

#### Go to the server directory

```bash
cd /opt/itential/platform/server
```

#### Run the key rotation utility

Run the command that matches how you configure Platform. Replace `$OLD_KEY` with your current encryption key and `$NEW_KEY` with your new encryption key.

* If you use a `platform.properties` file, run the following command:

  ```bash
  npm run key:rotate -- \
    --config-file /etc/itential/platform.properties \
    --old-encryption-key "$OLD_KEY" \
    --new-encryption-key "$NEW_KEY"
  ```

* If environment variables fully define your configuration, run the following command. Use `--only-env` in place of `--config-file`.

  ```bash
  npm run key:rotate -- \
    --only-env \
    --old-encryption-key "$OLD_KEY" \
    --new-encryption-key "$NEW_KEY"
  ```

#### Rotate custom collections (optional)

If you have custom collections that contain encrypted values, add them with `--extra-collections`. Repeat the option for each collection.

```bash
npm run key:rotate -- \
  --config-file /etc/itential/platform.properties \
  --old-encryption-key "$OLD_KEY" \
  --new-encryption-key "$NEW_KEY" \
  --extra-collections custom-collection-1 \
  --extra-collections custom-collection-2
```

#### Update encrypted values in your configuration

If your configuration contains encrypted values, the utility outputs their rotated counterparts. In your configuration file or environment variables, replace each existing value with its new value.

#### Start Platform

> **Warning**
>
> Don't start Platform instances until you update every encrypted value in your configuration with its rotated counterpart.

Configure Platform to use the new encryption key, and then start it.

```bash
sudo systemctl start itential-platform
```

## Command options

The key rotation utility supports the following options:

| Option                 | Alias | Description                                                                                                                                                       |
| ---------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--old-encryption-key` | `-o`  | The current encryption key.                                                                                                                                       |
| `--new-encryption-key` | `-n`  | The new encryption key.                                                                                                                                           |
| `--config-file`        | `-f`  | The path to the Platform configuration file.                                                                                                                      |
| `--only-env`           |       | Reads configuration only from environment variables. Use this option in place of `--config-file` when environment variables completely define your configuration. |
| `--extra-collections`  | `-c`  | A custom collection to rotate in addition to the default collections. Repeat the option for each collection.                                                      |
| `--only-collections`   | `-q`  | Rotates only the specified collections. For more information, see [Choose which collections to rotate](#choose-which-collections-to-rotate).                      |

## Choose which collections to rotate

By default, the utility rotates the following collections:

* `service_configs`
* `oauth_clients`
* `accounts`
* `iap_profiles`
* `itential_provider_profiles`
* `itential_agent_sessions`

To add collections to this list, use `--extra-collections`.

To rotate a specific set of collections instead, use `--only-collections`. The utility then rotates only the collections that you specify. It ignores the default collections and any collections that you pass with `--extra-collections`.