List regional secret versions and view 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

Go to the Secret Manager page in the Google Cloud console.

Go to Secret Manager
On the Secret Manager page, click the Regional secrets tab.
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 or fully qualified identifier for the secret.
LOCATION: the Google Cloud location of the secret

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud secrets versions list SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets versions list SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets versions list SECRET_ID --location=LOCATION

The response contains the secret.

REST

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

LOCATION: the Google Cloud location of the secret
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:

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

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 GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions"

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 GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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
}

Go

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

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
	"google.golang.org/api/iterator"
	"google.golang.org/api/option"
)

// listSecretVersions lists all secret versions in the given secret and their
// metadata.
func ListRegionalSecretVersions(w io.Writer, projectId, locationId, secretId string) error {
	// parent := "projects/my-project/locations/my-location/secrets/my-secret"

	// Create the client.
	ctx := context.Background()
	//Endpoint to send the request to regional server
	endpoint := fmt.Sprintf("secretmanager.%s.rep.googleapis.com:443", locationId)
	client, err := secretmanager.NewClient(ctx, option.WithEndpoint(endpoint))

	if err != nil {
		return fmt.Errorf("failed to create regional secretmanager client: %w", err)
	}
	defer client.Close()

	parent := fmt.Sprintf("projects/%s/locations/%s/secrets/%s", projectId, locationId, secretId)
	// Build the request.
	req := &secretmanagerpb.ListSecretVersionsRequest{
		Parent: parent,
	}

	// Call the API.
	it := client.ListSecretVersions(ctx, req)
	for {
		resp, err := it.Next()
		if err == iterator.Done {
			break
		}

		if err != nil {
			return fmt.Errorf("failed to list regional secret versions: %w", err)
		}

		fmt.Fprintf(w, "Found regional secret version %s with state %s\n",
			resp.Name, resp.State)
	}

	return nil
}

Java

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

import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient.ListSecretVersionsPagedResponse;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretName;
import java.io.IOException;

public class ListRegionalSecretVersions {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // Your GCP project ID.
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // Resource ID of the secret.
    String secretId = "your-secret-id";
    listRegionalSecretVersions(projectId, locationId, secretId);
  }

  // List all secret versions for a secret.
  public static ListSecretVersionsPagedResponse listRegionalSecretVersions(
      String projectId, String locationId, String secretId)
      throws IOException {

    // Endpoint to call the regional secret manager sever
    String apiEndpoint = String.format("secretmanager.%s.rep.googleapis.com:443", locationId);
    SecretManagerServiceSettings secretManagerServiceSettings =
        SecretManagerServiceSettings.newBuilder().setEndpoint(apiEndpoint).build();

    // Initialize the client that will be used to send requests. This client only needs to be
    // created once, and can be reused for multiple requests.
    try (SecretManagerServiceClient client = 
        SecretManagerServiceClient.create(secretManagerServiceSettings)) {
      // Build the parent name.
      SecretName secretName = 
          SecretName.ofProjectLocationSecretName(projectId, locationId, secretId);

      // Get all versions.
      ListSecretVersionsPagedResponse pagedResponse = client.listSecretVersions(secretName);

      // List all versions and their state.
      pagedResponse
          .iterateAll()
          .forEach(
              version -> {
                System.out.printf("Regional secret version %s, %s\n", 
                    version.getName(), version.getState());
              });

      return pagedResponse;
    }
  }
}

Node.js

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my-project';
// const locationId = 'my-location';
// const secretId = 'my-secret';

const parent = `projects/${projectId}/locations/${locationId}/secrets/${secretId}`;

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Adding the endpoint to call the regional secret manager sever
const options = {};
options.apiEndpoint = `secretmanager.${locationId}.rep.googleapis.com`;

// Instantiates a client
const client = new SecretManagerServiceClient(options);

async function listRegionalSecretVersions() {
  const [versions] = await client.listSecretVersions({
    parent: parent,
  });

  versions.forEach(version => {
    console.log(`${version.name}: ${version.state}`);
  });
}

listRegionalSecretVersions();

Python

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

# Import the Secret Manager client library.
from google.cloud import secretmanager_v1


def list_regional_secret_versions(
    project_id: str, location_id: str, secret_id: str
) -> None:
    """
    Lists all secret versions in the given secret and their metadata.
    """

    # Endpoint to call the regional secret manager sever.
    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"

    # Create the Secret Manager client.
    client = secretmanager_v1.SecretManagerServiceClient(
        client_options={"api_endpoint": api_endpoint},
    )

    # Build the resource name of the parent secret.
    parent = f"projects/{project_id}/locations/{location_id}/secrets/{secret_id}"

    # List all secret versions.
    for version in client.list_secret_versions(request={"parent": parent}):
        print(f"Found secret version: {version.name}")

Get details about a secret version

This process lets you view the metadata of a secret version such as the version ID, creation date and time, encryption details, and status. Viewing the metadata of a secret version means accessing information about the secret version, but not the actual secret value itself. To view the secret value, see Access a regional secret version.

To view a secret version's metadata, use one of the following methods:

Console

Go to the Secret Manager page in the Google Cloud console.

Go to Secret Manager
On the Secret Manager page, click the Regional secrets tab.
Click a secret to access its versions.

The versions belonging to the secret are displayed in the Versions table. For each version, the version ID and its metadata is also displayed in the table.

gcloud

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

VERSION_ID: the ID of the secret version
SECRET_ID: the ID of the secret or fully qualified identifier for the secret.
LOCATION: the Google Cloud location of the secret

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID --location=LOCATION

The response contains the secret.

REST

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

LOCATION: the Google Cloud location of the secret
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 secret version

HTTP method and URL:

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID

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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID"

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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

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

Go

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

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
	"google.golang.org/api/option"
)

// getSecretVersion gets information about the given secret version. It does not
// include the payload data.
func GetRegionalSecretVersion(w io.Writer, projectId, locationId, secretId, versionId string) error {
	// name := "projects/my-project/locations/my-location/secrets/my-secret/versions/5"
	// name := "projects/my-project/locations/my-location/secrets/my-secret/versions/latest"

	// Create the client.
	ctx := context.Background()
	//Endpoint to send the request to regional server
	endpoint := fmt.Sprintf("secretmanager.%s.rep.googleapis.com:443", locationId)
	client, err := secretmanager.NewClient(ctx, option.WithEndpoint(endpoint))

	if err != nil {
		return fmt.Errorf("failed to create regional secretmanager client: %w", err)
	}
	defer client.Close()

	name := fmt.Sprintf("projects/%s/locations/%s/secrets/%s/versions/%s", projectId, locationId, secretId, versionId)
	// Build the request.
	req := &secretmanagerpb.GetSecretVersionRequest{
		Name: name,
	}

	// Call the API.
	result, err := client.GetSecretVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to get regional secret version: %w", err)
	}

	fmt.Fprintf(w, "Found regional secret version %s with state %s\n",
		result.Name, result.State)
	return nil
}

Java

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

import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretVersion;
import com.google.cloud.secretmanager.v1.SecretVersionName;
import java.io.IOException;

public class GetRegionalSecretVersion {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // Your GCP project ID.
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // Resource ID of the secret.
    String secretId = "your-secret-id";
    // Version of the Secret ID you want to retrieve.
    String versionId = "your-version-id";
    getRegionalSecretVersion(projectId, locationId, secretId, versionId);
  }

  // Get an existing secret version.
  public static SecretVersion getRegionalSecretVersion(
      String projectId, String locationId, String secretId, String versionId)
      throws IOException {

    // Endpoint to call the regional secret manager sever
    String apiEndpoint = String.format("secretmanager.%s.rep.googleapis.com:443", locationId);
    SecretManagerServiceSettings secretManagerServiceSettings =
        SecretManagerServiceSettings.newBuilder().setEndpoint(apiEndpoint).build();

    // Initialize the client that will be used to send requests. This client only needs to be
    // created once, and can be reused for multiple requests.
    try (SecretManagerServiceClient client = 
        SecretManagerServiceClient.create(secretManagerServiceSettings)) {
      // Build the name from the version.
      SecretVersionName secretVersionName = 
          SecretVersionName.ofProjectLocationSecretSecretVersionName(
          projectId, locationId, secretId, versionId);

      // Create the secret.
      SecretVersion version = client.getSecretVersion(secretVersionName);
      System.out.printf("Regional secret version %s, state %s\n", 
          version.getName(), version.getState());

      return version;
    }
  }
}

Node.js

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// const projectId = 'my-project';
// const locationId = 'my-location';
// const secretId = 'my-secret';
// const versionId = 'my-version';

const name = `projects/${projectId}/locations/${locationId}/secrets/${secretId}/versions/${version}`;

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Adding the endpoint to call the regional secret manager sever
const options = {};
options.apiEndpoint = `secretmanager.${locationId}.rep.googleapis.com`;

// Instantiates a client
const client = new SecretManagerServiceClient(options);

async function getRegionalSecretVersion() {
  const [version] = await client.getSecretVersion({
    name: name,
  });

  console.info(`Found secret ${version.name} with state ${version.state}`);
}

getRegionalSecretVersion();

Python

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

# Import the Secret Manager client library.
from google.cloud import secretmanager_v1


def get_regional_secret_version(
    project_id: str,
    location_id: str,
    secret_id: str,
    version_id: str,
) -> secretmanager_v1.GetSecretVersionRequest:
    """
    Gets information about the given secret version. It does not include the
    payload data.
    """

    # Endpoint to call the regional secret manager sever.
    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"

    # Create the Secret Manager client.
    client = secretmanager_v1.SecretManagerServiceClient(
        client_options={"api_endpoint": api_endpoint},
    )

    # Build the resource name of the secret version.
    name = f"projects/{project_id}/locations/{location_id}/secrets/{secret_id}/versions/{version_id}"

    # Get the secret version.
    response = client.get_secret_version(request={"name": name})

    # Print information about the secret version.
    state = response.state.name
    print(f"Got secret version {response.name} with state {state}")

    return response

What's next

Assign an alias to a secret version