Update external key reference

This page shows you how to update the external key reference for aCloud EKM key without rotating the key. The new key reference mustpoint to the same key material as the current key reference. If the key materialhas been rotated in the external key management partner system, you mustrotate thekey instead.

Use the instructions on this page if your external key management partner system has changed thekey reference for an existing key. For example, the key reference canchange as a result of a change to the hostname of the external key management partner or achange in their key reference structure.

Required roles

To get the permission that you need to update an external key reference, ask your administrator to grant you theCloud KMS Admin (roles/cloudkms.admin) IAM role on your key. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the cloudkms.cryptoKeyVersions.update permission, which is required to update an external key reference.

You might also be able to get this permission withcustom roles or otherpredefined roles.

Update the URI for a key version without rotation

To update the key reference for a Cloud EKM key that you use over theinternet, complete the following steps:

Console

  1. In the Google Cloud console, go to theKey Management page.

    Go to Key Management

  2. Select the key ring, and then select the key and version.

  3. ClickMore, and then clickView key URI.

  4. ClickUpdate key URI.

  5. Enter the new key URI, and then clickSave.

gcloud CLI

To update the URI for the key version, use thegcloud kms versions updatecommand:

gcloud kms keys versions updateKEY_VERSION \  --keyKEY_NAME \  --keyringKEY_RING \  --locationLOCATION \  --external-key-uriNEW_KEY_URI

Replace the following:

  • KEY_VERSION: the key version number.
  • KEY_NAME: the name of the key.
  • KEY_RING: the name of the key ring that contains the key.
  • LOCATION: the Cloud KMS location of the key ring.
  • NEW_KEY_URI: the new URI for the existing externalkey material.

Update the key path for a key version without rotation

To update the key reference for a Cloud EKM key that you use over aVPC network, complete the following steps:

Console

  1. In the Google Cloud console, go to theKey Management page.

    Go to Key Management

  2. Select the key ring, and then select the key and version.

  3. ClickMorethenView key path.

  4. ClickUpdate key path.

  5. Enter the new key path, then clickSave.

gcloud CLI

To update the key path of the key version, use thegcloud kms versionsupdate command:

gcloud kms keys versions updateKEY_VERSION \  --keyKEY_NAME \  --keyringKEY_RING \  --locationLOCATION \  --ekm-connection-key-pathNEW_KEY_PATH

Replace the following:

  • KEY_VERSION: the key version number.
  • KEY_NAME: the name of the key.
  • KEY_RING: the name of the key ring that contains the key.
  • LOCATION: the Cloud KMS location of the key ring.
  • NEW_KEY_PATH: the new path for the existing externalkey material.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.