Delay destruction of secret versions

This page explains how to set up the delayed destruction of secret versions, update or remove the destruction delay duration, and restore secret versions that are scheduled for destruction.

When you destroy a secret version, the secret material is destroyed immediately and permanently. As the Secret Manager Admin, you can set up delayed destruction of secret versions such that the secret version isn't destroyed immediately upon request and remains recoverable for a configurable duration.

When delayed destruction is enabled on the secret and you destroy a secret version, the following occurs:

• The version is disabled, preventing its use.
• The system schedules the version for permanent destruction at the end of the delay period.
• After the delay period expires, the secret version is permanently and irrevocably destroyed.

Benefits

This feature provides the following benefits:

• An extra layer of protection against accidental or malicious destruction of critical secret material. Any user with the Secret Manager Secret Version Manager role can destroy a secret version. This is an irreversible action. By setting up delayed destruction, you can prevent the immediate destruction of secret versions. You can grant users the minimum access required to manage the lifecycle of secret versions because you can monitor and prevent any accidental destruction of sensitive data.

• Destroying a secret version triggers a SECRET_VERSION_DESTROY_SCHEDULED notification to the Pub/Sub topics configured on the secret. As a Secret Manager Admin, you can cancel the scheduled destruction and restore the secret version by either enabling or disabling the secret version.

Before you begin

• Enable the Secret Manager API.

  Enable the API

• Set up authentication.

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to set up delayed destruction of secret versions, ask your administrator to grant you the Secret Manager Admin (roles/secretmanager.admin) IAM role on the secret. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Set up delayed destruction

You can enable the delayed destruction of a secret version when you create the secret or when you update the secret.

Console

1. In the Google Cloud console, go to the Secret Manager page.

   Go to Secret Manager

2. Follow the steps required to create a secret.

3. Go to the Delay secret version destroy section.

4. Select the Set duration for delayed destruction checkbox.

5. In the Destruction delay duration field, enter the duration in days. The minimum value that you can enter is 1 day while the maximum value is 1000 days.

6. Click Create secret.

To enable this feature on an existing secret, go to the Edit secret page and then configure the destruction delay duration.

gcloud

To configure the destruction delay duration on the secret, use the gcloud secrets create command.

Before using any of the command data below, make the following replacements:

• SECRET_ID: the ID of the secret or fully qualified identifier for the secret.
• TTL_DURATION: the destruction delay duration for the secret versions. You can enter the duration in any format, for example, days, hours, or seconds. The minimum duration required is 1 day while maximum duration can be set to 1000 days.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION

The response contains the newly created secret.

REST

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID.
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret.
• TTL_DURATION: the destruction delay duration for the secret versions. Enter duration in seconds. Note that the minimum duration required is 1 day while maximum duration can be set to 1000 days.

HTTP method and URL:

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID

Request JSON body:

{"replication": {"automatic": {}}, "version_destroy_ttl":"TTL_DURATION"}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
"name":"projects/PROJECT_ID/secrets/SECRET_ID",
"replication":{
   "automatic":{

   }
},
"createTime":"2023-10-16T17:10:16.345401Z",
"etag":"\"1607d90ee3d84c\"",
"versionDestroyTtl":"TTL_DURATION"
}

Delayed destruction doesn't apply in the following scenarios:

• When a secret is deleted, all the secret material and related secret versions are deleted immediately.
• When an expiration date is set on the secret and the secret expires, all the secret versions are destroyed immediately even if delayed destruction is enabled on the secret.

Update destruction delay duration

Console

1. In the Google Cloud console, go to the Secret Manager page.

   Go to Secret Manager

2. Edit your secret using one of the following options:

   • Click More actions associated with the secret that you want to edit, and then select Edit from the menu.
   • Click the secret name to go to the Secret details page. On the Secret details page, click Edit secret.

3. Go to the Delay secret version destroy section.

4. In the Destruction delay duration field, enter the updated duration.

5. Click Update Secret.

gcloud

To update the destruction delay duration, use the gcloud secrets update command.

Before using any of the command data below, make the following replacements:

• SECRET_ID: the ID of the secret or fully qualified identifier for the secret
• TTL_DURATION: the destruction delay duration for the secret versions

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION

The response contains the newly created secret.

REST

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret
• TTL_DURATION: the destruction delay duration for the secret versions

HTTP method and URL:

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl

Request JSON body:

{
  "version_destroy_ttl":"TTL_DURATION"
}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID",
  "replication":{
     "automatic":{

     }
  },
  "createTime":"2023-10-16T17:10:16.345401Z",
  "etag":"\"1607d90ee3d84c\"",
  "versionDestroyTtl":"TTL_DURATION"
}

The secret versions that are affected by the destruction delay duration depends on the following:

• When delayed destruction is set for the first time on the secret, the destruction delay duration affects all the active (enabled and disabled) versions of the secret.
• When the destruction delay duration is updated or removed, the changes reflect only on new secret versions on which the destroy action is attempted. The secret versions that are already scheduled for destruction will continue to be destroyed at the scheduled destruction time.

Disable delayed destruction

Console

1. In the Google Cloud console, go to the Secret Manager page.

   Go to Secret Manager

2. Edit your secret using one of the following options:

   • Click More actions associated with the secret that you want to edit, and then select Edit from the menu.
   • Click the secret name to go to the Secret details page. On the Secret details page, click Edit secret.

3. Go to the Delay secret version destroy section.

4. Clear the Set duration for delayed destruction checkbox.

5. Click Update Secret.

gcloud

To remove the destruction delay duration, use the gcloud secrets update command.

Before using any of the command data below, make the following replacements:

• SECRET_ID: the ID of the secret or fully qualified identifier for the secret

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets update SECRET_ID --remove-version-destroy-ttl

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets update SECRET_ID --remove-version-destroy-ttl

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets update SECRET_ID --remove-version-destroy-ttl

REST

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret

HTTP method and URL:

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl

Request JSON body:

{}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID",
  "replication":{
     "automatic":{

     }
  },
  "createTime":"2023-10-16T17:10:16.345401Z",
  "etag":"\"1607d90ee3d84c\""
}

Test delayed destruction of secret versions

Console

1. In the Google Cloud console, go to the Secret Manager page.

   Go to Secret Manager

2. Click the secret name. The Secret details page appears.

3. On the Secret details page, in the Versions table, select a secret version.

4. In the Actions column, click View more, and then click Destroy.

5. In the dialog that appears, click Schedule selected versions for destruction.

gcloud

To destroy a secret version, use the gcloud secrets versions destroy command.

Before using any of the command data below, make the following replacements:

• SECRET_VERSION_ID: the ID of the version or fully qualified identifier for the version
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

REST

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret
• VERSION_ID: the ID of the version or fully qualified identifier for the version

HTTP method and URL:

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:destroy

Request JSON body:

{}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:destroy"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:destroy" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime":"2023-10-16T17:21:55.920036Z",
  "state":"DISABLED",
  "replicationStatus":{
     "automatic":{

     }
  },
  "etag":"\"1607d8b2fc1cf4\"",
  "scheduledDestroyTime":"2023-10-16T17:26:57.459395960Z"
}

The secret version is immediately disabled and scheduled for destruction after the destruction delay duration expires. You can see the exact date and time on which the version will be destroyed under the Scheduled for destruction on column in the Versions table.

Restore secret versions

You can restore a secret version that is scheduled for destruction by enabling or disabling the secret version.

Enable a secret version that is scheduled for destruction

Console

1. In the Google Cloud console, go to the Secret Manager page.

   Go to Secret Manager

2. Click the secret name. The Secret details page appears.

3. On the Secret details page, in the Versions table, select a secret version that is scheduled for destruction.

4. In the Actions column, click View more, and then click Enable.

5. In the dialog that appears, click Enable selected versions.

gcloud

To enable a secret version that is scheduled for destruction, use the gcloud secrets versions enable command.

Before using any of the command data below, make the following replacements:

• SECRET_VERSION_ID: the ID of the version or fully qualified identifier for the version
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

REST

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret
• VERSION_ID: the ID of the version or fully qualified identifier for the version

HTTP method and URL:

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:enable

Request JSON body:

{}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:enable"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:enable" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime": "2024-09-04T06:41:57.859674Z",
  "state": "ENABLED",
  "etag": "\"1621457b3c1459\""
}

Disable a secret version that is scheduled for destruction

Console

1. In the Google Cloud console, go to the Secret Manager page.

   Go to Secret Manager

2. Click the secret name. The Secret details page appears.

3. On the Secret details page, in the Versions table, select a secret version that is scheduled for destruction.

4. In the Actions column, click View more, then click Disable.

5. In the dialog that appears, click Disable selected versions.

gcloud

To disable a secret version that is scheduled for destruction, use the gcloud secrets versions disable command.

Before using any of the command data below, make the following replacements:

• SECRET_VERSION_ID: the ID of the version or fully qualified identifier for the version
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

The response contains the disabled version of the secret.

REST

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret
• VERSION_ID: the ID of the version or fully qualified identifier for the version

HTTP method and URL:

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable

Request JSON body:

{}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime":"2023-10-16T17:21:55.920036Z",
  "state":"DISABLED",
  "replicationStatus":{
     "automatic":{

     }
  },
  "etag":"\"1607d8b3e8e1bc\""
}

What's next

• Learn how to ensure data integrity.
• Learn about best practices.