All Products
Search

This Product

    Key Management Service:Change a client key

    Document Center

    Key Management Service:Change a client key

    Last Updated:Mar 31, 2026

    Client keys are valid for one to five years. Rotate client keys annually to reduce the risk of key compromise. If your client key is about to expire, change it at the earliest opportunity. If a key expires, applications using it lose access to Key Management Service (KMS).

    The rotation process has four steps: create a new client key, update your application to use it, verify the old key is no longer in use, then delete the old key. Throughout this process, you can track old key usage in KMS audit logs under Security Operations > Simple Log Service for KMS.

    Prerequisites

    Before you begin, ensure that you have:

    • An application access point (AAP) in the KMS console

    • Access to the application code or configuration that references the current client key

    Step 1: Create a client key

    1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > AAPs.KMS console

    2. Click the Application Access tab. Search for the AAP by Instance ID or AAP name.

    3. Click the AAP name. On the details page, click the Client Key tab, then click Create Client Key.

    4. In the Create Client Key panel, configure the following parameters:

      ParameterDescription
      Encryption Password8–64 characters. Allowed characters: digits, letters, and ~ ! @ # $ % ^ & * ? _ -
      Validity PeriodDefaults to five years. Set to one year to reduce the risk of key compromise.

    5. Click OK. The browser downloads two files automatically:

      • clientKey_****.json — contains the Application Access Secret (ClientKeyContent)

      • clientKey_****_Password.txt — contains the Password

      Store both files securely before proceeding.

    Step 2: Change the client key of a self-managed application

    Update your application to use the new client key files downloaded in Step 1.

    Using KMS instance SDK (Java) as an example, replace the following values when creating a client:

    • clientKeyPass — replace with the new Password

    • clientKeyFilePath or clientKey — replace with the new credential file or content

    Step 3: Verify the old client key is inactive

    Before deleting the old client key, confirm no application is still using it.

    1. Get the ID of the old client key from the Client Key tab.image.png

    2. In the left-side navigation pane, choose Security Operations > Simple Log Service for KMS. Select your instance ID.

    3. Enter the old client key ID in the search box under kms_audit_log.image.png

    If the search returns results, the key is still in use. Use the client_ip and useragent fields to identify which applications have not been updated. Repeat Step 2 for those applications, then re-check the logs.

    Step 4: Delete the old client key

    Warning

    Deletion takes effect immediately. Before you delete a client key, make sure that the client key is no longer in use. Otherwise, your applications may fail to access the required KMS instance.

    1. On the Client Key tab, find the old client key and click Delete in the Actions column.

    2. In the Delete Client Key message, click OK.

    3. Complete security verification. Then, KMS deletes the client key.