View secret version details

This page describes how to retrieve a list of all the different versions of a secret that have been created over time and view the metadata of a specific secret version.

Required roles

To get the permissions that you need to list secret versions and view version details, ask your administrator to grant you the Secret Manager Viewer (roles/secretmanager.viewer) IAM role on the secret, project, folder, or organization. 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.

List a secret's versions

Listing a secret's versions is useful in the following ways:

  • You can see see how a secret has changed over time, who made the changes, and when. This is required for auditing and compliance.

  • You can roll back to a previous, known-good version if a secret is accidentally updated or compromised.

  • You can identify versions that are no longer in use and can be safely deleted.

  • You can troubleshoot issues. For example, if an application is experiencing problems, you can examine previous versions of a secret to see if a change to the secret is the cause.

To list all the versions of a secret, use one of the following methods:

Console

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

    Go to Secret Manager

  2. Click a secret to access its versions.

    The versions belonging to the secret are displayed in the Versions table.

gcloud

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

  • SECRET_ID: the ID of the secret

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud secrets versions list SECRET_ID

Windows (PowerShell)

gcloud secrets versions list SECRET_ID

Windows (cmd.exe)

gcloud secrets versions list SECRET_ID

The response contains 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

HTTP method and URL: 

GET https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions

Request JSON body: 

{}

To send your request, choose one of these options:

curl

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

curl -X GET \
     -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"

PowerShell

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 GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

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

C#

To run this code, first set up a C# development environment and install the Secret Manager C# SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope. 


using Google.Cloud.SecretManager.V1;

public class ListSecretVersionsSample
{
    public void ListSecretVersions(string projectId = "my-project", string secretId = "my-secret")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the resource name.
        SecretName secretName = new SecretName(projectId, secretId);

        // Call the API.
        foreach (SecretVersion secretVersion in client.ListSecretVersions(secretName))
        {
            // ...
        }