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.
-
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
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
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.
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.
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.
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.
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.
-
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.
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.
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.
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.