Destroy and restore key versions Stay organized with collections Save and categorize content based on your preferences.
This page shows you how to schedule a Cloud Key Management Service key version for permanentdestruction. In Cloud KMS, the cryptographic key material that you useto encrypt, decrypt, sign, and verify data is stored in akey version. A keyhas zero or more key versions. When you rotate a key, you create a new keyversion.
Destroying a key version means that the key material is permanently deleted.When you destroy a key version, other details such as the key name and keyversion number aren't deleted. After a key is destroyed, data that was encryptedwith the key version can't be decrypted.
The only exception iskey re-import,which lets you restore a previously imported key by providing the same originalkey material.
Because key destruction is generally irreversible, Cloud KMS doesn'tlet you destroy key versions immediately. Instead, you schedule a key versionfor destruction. The key version remains in the scheduled for destructionstate for a configurable time. During the scheduled for destruction duration,you can restore a key version to cancel its destruction.
The default scheduled for destruction duration is 30 days. You canset acustom scheduled for destruction duration for a key during keycreation. Your organization can enforcea minimum scheduled for destruction duration by setting theMinimum destroyscheduled duration per key constraint in your organization policies.
You can also manage access to the key using Identity and Access Management (IAM).IAM operations are consistent within seconds. For moreinformation, seeUsing IAM.
Caution: Destroying a key is a permanent operation that can cause unrecoverabledata loss. Make sure that youunderstand the risks beforedestroying a key version.You can also temporarilydisable a key version. Werecommend disabling key versions prior to scheduling them for destruction aspart of your procedures for ensuring that the key can be safely destroyed.Depending on your organization policies, you might be required to disable a keyversion before you can schedule it for destruction. For more information aboutcontrolling key version destruction using organization policies, seeControlkey version destruction.
Note: Key rings, keys, and key versions cannot be deleted. This ensures that theresource identifier of akey version is unique and always points to the original key material for that key version unless ithas been destroyed.You can store an unlimited number of key rings, enabled or disabled keys, andenabled, disabled, or destroyed key versions.For more information, seePricing andQuotas.In the rest of this document, scheduling a key for destruction is referred toas destroying the key, even though destruction is not immediate.
Before you begin
Understand the risks
Destroying a key version is a permanent operation. Destroying a key version thatis still needed has risks including the following:
Service outage: If you destroy a key that is required to start a containeror instance, your services or applications can become unavailable.
Permanent data loss: If you destroy a key that was used to encrypt data,that data becomes unavailable. Data encrypted with a key that has beendestroyed is consideredcrypto-shredded. In some cases, destroying a keycan cause encrypted resources to be permanently deleted.
Regulatory or compliance issues: If you destroy a key that is required toaccess data that is subject to a retention period before that retentionperiod is complete, you might be in violation of a regulatory or compliancerequirement.
Required roles
To get the permissions that you need to destroy and restore key versions, ask your administrator to grant you theCloud KMS Admin (roles/cloudkms.admin) IAM role on the key. For more information about granting roles, seeManage access to projects, folders, and organizations.
You might also be able to get the required permissions throughcustom roles or otherpredefined roles.
Check whether the key version is in use
Before you destroy a key version, complete the following steps to see whetherthe key version is in use:
View key usage tracking details for the key.If any resources are protected by the key version that you want to destroy,re-encrypt them with another key version.
Caution: Key usage tracking details can be delayed or incomplete.Familiarize yourself with thelimitations of this data.Turn on logs for any service or application that could be using the keyversion.
Turn on logs on the Cloud KMS project that contains the key.
Disable the key version. Disabling the keyversion prevents the key version from being used. With thekey version disabled, any attempts to use the key version fail.
Monitor the logs until you're sure that no application or service stillrelies on the key version that you disabled. If any errors indicate failedaccess to the key version, configure the application or resource to useanother key version.
The length of time that you spend monitoring logs before destroying akey version depends on the type of key, its usage pattern, and itssensitivity level. For example, before destroying a key version that is usedin a process that runs quarterly, keep the key version disabled until thatprocess completes successfully.
Check the usage of the key against any applicable compliance requirements.For example, the key version and data encrypted with it may be subject todata retention periods.
These steps help you to identify whether a key might still be needed; however,they can't guarantee that a key version is no longer needed. Your organizationshould implement procedures and guidelines to ensure that key versiondestruction won't cause negative effects.
Warning: It is your responsibility to ensure that a key version issafe to destroy. Google is not responsible for outages, loss of data, orcompliance issues that result from you destroying a key version.Destroy a key version
You can destroy an enabled or disabled key version.
Caution: Key material isn't immediately destroyed. Instead, the key version stays scheduled for destruction for the configured scheduled for destruction duration. After this period has ended, the key material is automatically destroyed. There is no way to override this safety fallback.
If you decide that you don't want the destruction to occur, you canrestore the key version. However, after the configured scheduled for destruction duration, destruction isn't reversible. Any data encrypted with this key version can't be decrypted.
Console
In the Google Cloud console, go to theKey Management page.
Check the box next to the key version that you want to schedule fordestruction.
ClickDestroy in the header.
In the confirmation prompt, enter the key name and then clickScheduleDestruction.
gcloud
To use Cloud KMS on the command line, firstInstall or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys versions destroyKEY_VERSION \ --keyKEY_NAME \ --keyringKEY_RING \ --locationLOCATION
Replace the following:
KEY_VERSION: the version number of the key version that you wantto destroy.KEY_NAME: the name of the key for which you want to destroy a keyversion.KEY_RING: the name of the key ring that contains the key.LOCATION: the Cloud KMS location of the key ring.
For information on all flags and possible values, run the command with the--help flag.
C#
To run this code, firstset up a C# development environment andinstall the Cloud KMS C# SDK.
usingGoogle.Cloud.Kms.V1;publicclassDestroyKeyVersionSample{publicCryptoKeyVersionDestroyKeyVersion(stringprojectId="my-project",stringlocationId="us-east1",stringkeyRingId="my-key-ring",stringkeyId="my-key",stringkeyVersionId="123"){// Create the client.KeyManagementServiceClientclient=KeyManagementServiceClient.Create();// Build the key version name.CryptoKeyVersionNamekeyVersionName=newCryptoKeyVersionName(projectId,locationId,keyRingId,keyId,keyVersionId);// Call the API.CryptoKeyVersionresult=client.DestroyCryptoKeyVersion(keyVersionName);// Return the result.returnresult;}}Go
To run this code, firstset up a Go development environment andinstall the Cloud KMS Go SDK.
import("context""fmt""io"kms"cloud.google.com/go/kms/apiv1""cloud.google.com/go/kms/apiv1/kmspb")// destroyKeyVersion marks a specified key version for deletion. The key can be// restored if requested within 24 hours.funcdestroyKeyVersion(wio.Writer,namestring)error{// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/123"// Create the client.ctx:=context.Background()client,err:=kms.NewKeyManagementClient(ctx)iferr!=nil{returnfmt.Errorf("failed to create kms client: %w",err)}deferclient.Close()// Build the request.req:=&kmspb.DestroyCryptoKeyVersionRequest{Name:name,}// Call the API.result,err:=client.DestroyCryptoKeyVersion(ctx,req)iferr!=nil{returnfmt.Errorf("failed to destroy key version: %w",err)}fmt.Fprintf(w,"Destroyed key version: %s\n",result)returnnil}Java
To run this code, firstset up a Java development environment andinstall the Cloud KMS Java SDK.
importcom.google.cloud.kms.v1.CryptoKeyVersion;importcom.google.cloud.kms.v1.CryptoKeyVersionName;importcom.google.cloud.kms.v1.KeyManagementServiceClient;importjava.io.IOException;publicclassDestroyKeyVersion{publicvoiddestroyKeyVersion()throwsIOException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringlocationId="us-east1";StringkeyRingId="my-key-ring";StringkeyId="my-key";StringkeyVersionId="123";destroyKeyVersion(projectId,locationId,keyRingId,keyId,keyVersionId);}// Schedule destruction of the given key version.publicvoiddestroyKeyVersion(StringprojectId,StringlocationId,StringkeyRingId,StringkeyId,StringkeyVersionId)throwsIOException{// Initialize client that will be used to send requests. This client only// needs to be created once, and can be reused for multiple requests. After// completing all of your requests, call the "close" method on the client to// safely clean up any remaining background resources.try(KeyManagementServiceClientclient=KeyManagementServiceClient.create()){// Build the key version name from the project, location, key ring, key,// and key version.CryptoKeyVersionNamekeyVersionName=CryptoKeyVersionName.of(projectId,locationId,keyRingId,keyId,keyVersionId);// Destroy the key version.CryptoKeyVersionresponse=client.destroyCryptoKeyVersion(keyVersionName);System.out.printf("Destroyed key version: %s%n",response.getName());}}}Node.js
To run this code, firstset up a Node.js development environment andinstall the Cloud KMS Node.js SDK.
//// TODO(developer): Uncomment these variables before running the sample.//// const projectId = 'my-project';// const locationId = 'us-east1';// const keyRingId = 'my-key-ring';// const keyId = 'my-key';// const versionId = '123';// Imports the Cloud KMS libraryconst{KeyManagementServiceClient}=require('@google-cloud/kms');// Instantiates a clientconstclient=newKeyManagementServiceClient();// Build the key version nameconstversionName=client.cryptoKeyVersionPath(projectId,locationId,keyRingId,keyId,versionId);asyncfunctiondestroyKeyVersion(){const[version]=awaitclient.destroyCryptoKeyVersion({name:versionName,});console.log(`Destroyed key version:${version.name}`);returnversion;}returndestroyKeyVersion();PHP
To run this code, first learn aboutusing PHP on Google Cloud andinstall the Cloud KMS PHP SDK.
use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;use Google\Cloud\Kms\V1\DestroyCryptoKeyVersionRequest;function destroy_key_version( string $projectId = 'my-project', string $locationId = 'us-east1', string $keyRingId = 'my-key-ring', string $keyId = 'my-key', string $versionId = '123') { // Create the Cloud KMS client. $client = new KeyManagementServiceClient(); // Build the key version name. $keyVersionName = $client->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $keyId, $versionId); // Call the API. $destroyCryptoKeyVersionRequest = (new DestroyCryptoKeyVersionRequest()) ->setName($keyVersionName); $destroyedVersion = $client->destroyCryptoKeyVersion($destroyCryptoKeyVersionRequest); printf('Destroyed key version: %s' . PHP_EOL, $destroyedVersion->getName()); return $destroyedVersion;}Python
To run this code, firstset up a Python development environment andinstall the Cloud KMS Python SDK.
fromgoogle.cloudimportkmsdefdestroy_key_version(project_id:str,location_id:str,key_ring_id:str,key_id:str,version_id:str)->kms.CryptoKeyVersion:""" Schedule destruction of the given key version. Args: project_id (string): Google Cloud project ID (e.g. 'my-project'). location_id (string): Cloud KMS location (e.g. 'us-east1'). key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring'). key_id (string): ID of the key to use (e.g. 'my-key'). version_id (string): ID of the key version to destroy (e.g. '1'). Returns: CryptoKeyVersion: The version. """# Create the client.client=kms.KeyManagementServiceClient()# Build the key version name.key_version_name=client.crypto_key_version_path(project_id,location_id,key_ring_id,key_id,version_id)# Call the API.destroyed_version=client.destroy_crypto_key_version(request={"name":key_version_name})print(f"Destroyed key version:{destroyed_version.name}")returndestroyed_versionRuby
To run this code, firstset up a Ruby development environment andinstall the Cloud KMS Ruby SDK.
# TODO(developer): uncomment these values before running the sample.# project_id = "my-project"# location_id = "us-east1"# key_ring_id = "my-key-ring"# key_id = "my-key"# version_id = "123"# Require the library.require"google/cloud/kms"# Create the client.client=Google::Cloud::Kms.key_management_service# Build the key version name.key_version_name=client.crypto_key_version_pathproject:project_id,location:location_id,key_ring:key_ring_id,crypto_key:key_id,crypto_key_version:version_id# Call the API.destroyed_version=client.destroy_crypto_key_versionname:key_version_nameputs"Destroyed key version:#{destroyed_version.name}"API
These examples usecurl as an HTTP client to demonstrate using the API. For more information about access control, seeAccessing the Cloud KMS API.
Destroy a key version by calling theCryptoKeyVersions.destroymethod.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION:destroy" \ --request "POST" \ --header "authorization: BearerTOKEN"
If you're unable to destroy a key version, your organization might require thatkey versions be disabled before destruction. Try disabling the key versionbefore destroying it.
When you submit the destruction request, the state of the key version becomesscheduled for destruction. After the key'sconfiguredscheduled for destruction duration haspassed, the state of the key version becomes destroyed, meaninglogical deletion of the key material from activesystemshas started, and the key material can't be recovered by the customer. Keymaterial can remain in Google systems for up to45 days from thescheduled destruction time.
To receive an alert when a key version is scheduled for destruction, seeUsing Cloud Monitoring with Cloud KMS.
Destroyed key versions are not billed resources.
Note: Destroying all active key versions doesn't change the key's rotationschedule if one is configured. If you want to discontinue the automatic creationof new key versions, then you must alsodisable automaticrotation on the key. If you don't disable automaticrotation, new key versions continue to be created on schedule.Destroying external keys
To permanently remove the association between a Cloud EKM key and anexternal key, you can destroy the key version.After theScheduled for destruction period has passed, the key is destroyed.After the key version is destroyed, you can no longer encrypt data or decryptdata that was encrypted with the Cloud EKM key version.
Caution: You can't recreate a Cloud EKM key version that has beendestroyed, even if you use the same external key URI or key path.Destroying amanually managed key version in Cloud KMS doesn't modifythe key in the external key manager. We recommend first destroying the key orkey version in Google Cloud. After the Cloud EKM key version isdestroyed, you can destroy the key material in the external key manager.
Destroying acoordinated external key version in Cloud KMS firstdestroys the key version in Google Cloud, and then sends a destructionrequest to the EKM to destroy the external key material.
Restore a key version
During the period when the state of a key version is scheduled for destruction,you can restore the key version by submitting a restoration request.
Console
Go to theKey Management page in the Google Cloud console.
Click the name of the key ring that contains the key whose key version youwill restore.
Click the key whose key version you want to restore.
Check the box next to the key version that you want to restore.
ClickRestore in the header.
In the confirmation prompt, clickRestore.
gcloud
To use Cloud KMS on the command line, firstInstall or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys versions restorekey-version \ --keykey \ --keyringkey-ring \ --locationlocation
Replacekey-version with the version of the key to restore. Replacekey with the name of the key. Replacekey-ring withthe name of the key ring where the key is located. Replacelocationwith the Cloud KMS location for the key ring.
For information on all flags and possible values, run the command with the--help flag.
C#
To run this code, firstset up a C# development environment andinstall the Cloud KMS C# SDK.
usingGoogle.Cloud.Kms.V1;publicclassRestoreKeyVersionSample{publicCryptoKeyVersionRestoreKeyVersion(stringprojectId="my-project",stringlocationId="us-east1",stringkeyRingId="my-key-ring",stringkeyId="my-key",stringkeyVersionId="123"){// Create the client.KeyManagementServiceClientclient=KeyManagementServiceClient.Create();// Build the key version name.CryptoKeyVersionNamecryptoKeyVersionName=newCryptoKeyVersionName(projectId,locationId,keyRingId,keyId,keyVersionId);// Call the API.CryptoKeyVersionresult=client.RestoreCryptoKeyVersion(cryptoKeyVersionName);// Return the result.returnresult;}}Go
To run this code, firstset up a Go development environment andinstall the Cloud KMS Go SDK.
import("context""fmt""io"kms"cloud.google.com/go/kms/apiv1""cloud.google.com/go/kms/apiv1/kmspb")// restoreKeyVersion attempts to recover a key that has been marked for// destruction in the past 24h.funcrestoreKeyVersion(wio.Writer,namestring)error{// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/123"// Create the client.ctx:=context.Background()client,err:=kms.NewKeyManagementClient(ctx)iferr!=nil{returnfmt.Errorf("failed to create kms client: %w",err)}deferclient.Close()// Build the request.req:=&kmspb.RestoreCryptoKeyVersionRequest{Name:name,}// Call the API.result,err:=client.RestoreCryptoKeyVersion(ctx,req)iferr!=nil{returnfmt.Errorf("failed to restore key version: %w",err)}fmt.Fprintf(w,"Restored key version: %s\n",result)returnnil}Java
To run this code, firstset up a Java development environment andinstall the Cloud KMS Java SDK.
importcom.google.cloud.kms.v1.CryptoKeyVersion;importcom.google.cloud.kms.v1.CryptoKeyVersionName;importcom.google.cloud.kms.v1.KeyManagementServiceClient;importjava.io.IOException;publicclassRestoreKeyVersion{publicvoidrestoreKeyVersion()throwsIOException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringlocationId="us-east1";StringkeyRingId="my-key-ring";StringkeyId="my-key";StringkeyVersionId="123";restoreKeyVersion(projectId,locationId,keyRingId,keyId,keyVersionId);}// Schedule destruction of the given key version.publicvoidrestoreKeyVersion(StringprojectId,StringlocationId,StringkeyRingId,StringkeyId,StringkeyVersionId)throwsIOException{// Initialize client that will be used to send requests. This client only// needs to be created once, and can be reused for multiple requests. After// completing all of your requests, call the "close" method on the client to// safely clean up any remaining background resources.try(KeyManagementServiceClientclient=KeyManagementServiceClient.create()){// Build the key version name from the project, location, key ring, key,// and key version.CryptoKeyVersionNamekeyVersionName=CryptoKeyVersionName.of(projectId,locationId,keyRingId,keyId,keyVersionId);// Restore the key version.CryptoKeyVersionresponse=client.restoreCryptoKeyVersion(keyVersionName);System.out.printf("Restored key version: %s%n",response.getName());}}}Node.js
To run this code, firstset up a Node.js development environment andinstall the Cloud KMS Node.js SDK.
//// TODO(developer): Uncomment these variables before running the sample.//// const projectId = 'my-project';// const locationId = 'us-east1';// const keyRingId = 'my-key-ring';// const keyId = 'my-key';// const versionId = '123';// Imports the Cloud KMS libraryconst{KeyManagementServiceClient}=require('@google-cloud/kms');// Instantiates a clientconstclient=newKeyManagementServiceClient();// Build the key version nameconstversionName=client.cryptoKeyVersionPath(projectId,locationId,keyRingId,keyId,versionId);asyncfunctionrestoreKeyVersion(){const[version]=awaitclient.restoreCryptoKeyVersion({name:versionName,});console.log(`Restored key version:${version.name}`);returnversion;}returnrestoreKeyVersion();PHP
To run this code, first learn aboutusing PHP on Google Cloud andinstall the Cloud KMS PHP SDK.
use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;use Google\Cloud\Kms\V1\RestoreCryptoKeyVersionRequest;function restore_key_version( string $projectId = 'my-project', string $locationId = 'us-east1', string $keyRingId = 'my-key-ring', string $keyId = 'my-key', string $versionId = '123') { // Create the Cloud KMS client. $client = new KeyManagementServiceClient(); // Build the key version name. $keyVersionName = $client->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $keyId, $versionId); // Call the API. $restoreCryptoKeyVersionRequest = (new RestoreCryptoKeyVersionRequest()) ->setName($keyVersionName); $restoredVersion = $client->restoreCryptoKeyVersion($restoreCryptoKeyVersionRequest); printf('Restored key version: %s' . PHP_EOL, $restoredVersion->getName()); return $restoredVersion;}Python
To run this code, firstset up a Python development environment andinstall the Cloud KMS Python SDK.
fromgoogle.cloudimportkmsdefrestore_key_version(project_id:str,location_id:str,key_ring_id:str,key_id:str,version_id:str)->kms.CryptoKeyVersion:""" Restore a key version scheduled for destruction. Args: project_id (string): Google Cloud project ID (e.g. 'my-project'). location_id (string): Cloud KMS location (e.g. 'us-east1'). key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring'). key_id (string): ID of the key to use (e.g. 'my-key'). version_id (string): ID of the version to use (e.g. '1'). Returns: CryptoKeyVersion: Restored Cloud KMS key version. """# Create the client.client=kms.KeyManagementServiceClient()# Build the key version name.key_version_name=client.crypto_key_version_path(project_id,location_id,key_ring_id,key_id,version_id)# Call the API.restored_version=client.restore_crypto_key_version(request={"name":key_version_name})print(f"Restored key version:{restored_version.name}")returnrestored_versionRuby
To run this code, firstset up a Ruby development environment andinstall the Cloud KMS Ruby SDK.
# TODO(developer): uncomment these values before running the sample.# project_id = "my-project"# location_id = "us-east1"# key_ring_id = "my-key-ring"# key_id = "my-key"# version_id = "123"# Require the library.require"google/cloud/kms"# Create the client.client=Google::Cloud::Kms.key_management_service# Build the key version name.key_version_name=client.crypto_key_version_pathproject:project_id,location:location_id,key_ring:key_ring_id,crypto_key:key_id,crypto_key_version:version_id# Call the API.restored_version=client.restore_crypto_key_versionname:key_version_nameputs"Restored key version:#{restored_version.name}"API
These examples usecurl as an HTTP client to demonstrate using the API. For more information about access control, seeAccessing the Cloud KMS API.
Restore a key version by calling theCryptoKeyVersions.restoremethod.
curl "https://cloudkms.googleapis.com/v1/projects/project-id/locations/location-id/keyRings/key-ring-id/cryptoKeys/crypto-key-id/cryptoKeyVersions/version-id:restore" \ --request "POST" \ --header "authorization: Bearertoken"
After the restoration request completes, the state of the key version becomesdisabled. You mustenable the key before it can be used.
Required IAM permissions
To destroy a key version, the caller needs thecloudkms.cryptoKeyVersions.destroy IAM permission on the key,the key ring, or the project, folder, or organization.
To restore a key version, the caller needs thecloudkms.cryptoKeyVersions.restore permission.
Both of these permissions are granted to the Cloud KMS Admin role(roles/cloudkms.admin).
Deletion timeline
Cloud KMS commits to deleting customer key material from all Googleinfrastructure within 45 days of the scheduled destruction time. This includesremoval of data from both active systems and data center backups. Other customerdata is subject to the standardGoogle Cloud deletion timelineof 180 days.
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-18 UTC.