---
title: Rotate keys
description: Key rotation is the process of generating a new version of a key, assigning that version, and then deprovisioning the old key.
component: web-agents
version: 2025.11
page_id: web-agents:maintenance-guide:rotate-keys
canonical_url: https://docs.pingidentity.com/web-agents/2025.11/maintenance-guide/rotate-keys.html
keywords: ["Maintenance", "Configuration", "Keys & Certificates"]
section_ids:
  why_and_when_to_rotate_keys: Why and when to rotate keys
  steps_for_rotating_keys: Steps for rotating keys
  considerations_if_key_rotation_fails: Considerations if key rotation fails
---

# Rotate keys

Key rotation is the process of generating a new version of a key, assigning that version, and then deprovisioning the old key.

## Why and when to rotate keys

Regular key rotation is a security consideration that is sometimes required for internal business compliance. Regularly rotate keys to:

* Limit the amount of data protected by a single key.

* Reduce dependence on specific keys, making it easier to migrate to stronger algorithms.

* Prepare for when a key is compromised. The first time you try key rotation shouldn't be during a real-time recovery.

Key revocation is a type of key rotation done exceptionally if you suspect that a key has been compromised. To decide when to revoke a key, consider the following points:

* If limited use of the old keys can be tolerated, provision the new keys and then deprovision the old keys. Messages produced before the new keys are provisioned are impacted.

* If use of the old keys can't be tolerated, deprovision the old keys before you provision the new keys. The system is unusable until new keys are provisioned.

## Steps for rotating keys

1. Stop the web server.

2. View a list of Web Agent instances, using the [`agentadmin --l`](../installation-guide/agentadmin.html#agentadmin-l) command.

3. Rotate the keys for a Web Agent instance, using the [`agentadmin --k --rotate agent-instance`](../installation-guide/agentadmin.html#agentadmin-k) command.

   The following example rotates keys for the instance `agent_3`:

   * Unix

   * Windows

   ```
   $ cd /path/to/web_agents/apache24_agent/bin/
   $ ./agentadmin --k --rotate agent_3

   Performing key rotation for instance: agent_3

   Instance config directory: /path/to/web_agents/apache24_agent/instances/agent_3
   Loading agent.conf…​done
   Loading current credentials…​done
   Generating new encryption key…​done
   Encrypting current credentials with new encryption key:
   	- Encrypting agent profile password with new key…​done
   	- Encrypting certificate password with new key…​done
   	- Encrypting http proxy password with new key…​done
   Performing file operations:
   Gathering file information for agent-key.conf
   Gathering file information for agent-password.conf
   Backing up key file to agent-key.conf.bak
   Backing up password file to agent-password.conf.bak
   Writing new key to agent-key.conf…​done
   Writing new ciphertexts to agent-password.conf…​done
   Successfully wrote new key and passwords to disk

   Removing backup agent-key.conf.bak…​done
   Removing backup agent-password.conf.bak…​done

   Key rotation was successful for instance: agent_3
   ```

   ```
   C:\> cd web_agents\iis_agent\bin
   C:\web_agents\iis_agent\bin> agentadmin.exe --k --rotate agent_3

   Performing key rotation for instance: agent_3

   Instance config directory: …​
   Loading agent.conf…​done
   Loading current credentials…​done
   Generating new encryption key…​done
   Encrypting current credentials with new encryption key:
   	- Encrypting agent profile password with new key…​done
   	- Encrypting certificate password with new key…​done
   	- Encrypting http proxy password with new key…​done
   Backing up key file to agent-key.conf.bak
   Backing up password file to agent-password.conf.bak
   Writing new key to agent-key.conf…​done
   Writing new ciphertexts to agent-password.conf…​done
   Successfully wrote new key and passwords to disk

   Removing backup agent-key.conf.bak…​done
   Removing backup agent-password.conf.bak…​done

   Key rotation was successful for instance: agent_3
   ```

## Considerations if key rotation fails

* If key rotation fails while the agent is updating `agent-password.conf` or `agent-key.conf`, the rotate command tries to revert to the original files.

* If the rotate command can't revert to the original files, manually move `agent-password.conf.bak` and `agent-key.conf.bak` to `agent-password.conf` and `agent-key.conf`.

* After a failed key rotation on Windows, look for and delete `.bak` files. Windows can't rename a file as `.bak` if a `.bak` file already exists.