You can assign aliases to secret versions for easier access. After an alias is assigned, you can
access the secret versions using their aliases in the same way that you can access secret versions by
their version number.

> [!IMPORTANT]
> **Important:** To use Secret Manager with workloads running on Compute Engine or Google Kubernetes Engine, the underlying instance or node must have the `cloud-platform` OAuth scope. See [accessing the Secret Manager API](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes) for more information.

## Required roles


To get the permissions that
you need to assign an alias to a secret version,

ask your administrator to grant you the
[Secret Manager Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/secretmanager.md.txt#secretmanager.admin) (`roles/secretmanager.admin`) IAM role on the secret, project, folder, or organization.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Assign an alias to a secret version

To assign an alias to a secret version, use one of the following methods:

> [!NOTE]
> **Note:** Alias names must start with a letter, can be up to 63 characters long, and can contain letters, numbers, hyphens (-), and underscores (_). You cannot use `Latest` or `New` (case-insensitive) as an alias name.
>
> <br />
>
### Console

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


   [Go to Secret Manager](https://console.cloud.google.com/security/secret-manager)
2. To edit a secret, use one of the following methods:

   - Click **Actions** for the secret
     that you want to edit, and then click **Edit**.

   - Click the secret name to go to the secret details page. On the secret details page,
     click **Edit secret**.

3. On the **Edit secret** page, go to **Version aliases** , and then
   click **Add alias**.

4. Do the following:

   1. Specify the alias name.

   2. Select the secret version to which you will assign this alias.

5. Click **Update secret**.

### gcloud


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

- <var translate="no">SECRET_ID</var>: the ID of the secret.
- <var translate="no">KEY</var>: the secret version alias name.
- <var translate="no">VALUE</var>: the secret version number.


Execute the

following

command:

#### Linux, macOS, or Cloud Shell

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud secrets update SECRET_ID \
  --update-version-aliases=KEY=VALUE
```

#### Windows (PowerShell)

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud secrets update SECRET_ID `
  --update-version-aliases=KEY=VALUE
```

#### Windows (cmd.exe)

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud secrets update SECRET_ID ^
  --update-version-aliases=KEY=VALUE
```


The response contains the updated secret.

### REST


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

- <var translate="no">PROJECT_ID</var>: the Google Cloud project ID.
- <var translate="no">SECRET_ID</var>: the ID of the secret.
- <var translate="no">KEY</var>: the secret version alias name.
- <var translate="no">VALUE</var>: the secret version number.


HTTP method and URL:

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


Request JSON body:

```
{'version_aliases': {'KEY': 'VALUE'}}
```

To send your request, choose one of these options:

#### curl

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


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_aliases"
```

#### PowerShell

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


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_aliases" | Select-Object -Expand Content
```

You should receive a JSON response similar to the following:

```
{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-04T06:34:32.995517Z",
  "etag": "\"16214584d1479c\"",
  "versionAliases": {
    "nonprod": "1"
  }
}
```

### C#

To run this code, first [set up a C# development environment](https://docs.cloud.google.com/dotnet/docs/setup.md.txt) and
[install the Secret Manager C# SDK](https://docs.cloud.google.com/secret-manager/docs/reference/libraries.md.txt#client-libraries-install-csharp).
On Compute Engine or GKE, you must
[authenticate with the cloud-platform scope](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes).

```c#

using Google.Protobuf.WellKnownTypes;
using Google.Cloud.SecretManager.V1;

public class UpdateSecretWithAliasSample
{
    public Secret UpdateSecret(string projectId = "my-project", string secretId = "my-secret")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the secret with updated fields.
        Secret secret = new Secret
        {
            SecretName = new SecretName(projectId, secretId),
            VersionAliases = { ["test"] = 1}
        };

        // Build the field mask.
        FieldMask fieldMask = FieldMask.FromString("version_aliases");

        // Call the API.
        Secret updatedSecret = client.UpdateSecret(secret, fieldMask);
        return updatedSecret;
    }
}
```

### Go

To run this code, first [set up a Go development environment](https://docs.cloud.google.com/go/docs/setup.md.txt) and
[install the Secret Manager Go SDK](https://docs.cloud.google.com/secret-manager/docs/reference/libraries.md.txt#client-libraries-install-go).
On Compute Engine or GKE, you must
[authenticate with the cloud-platform scope](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes).

```go
import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
	"google.golang.org/genproto/protobuf/field_mask"
)

// updateSecret updates the alias map on an existing secret.
func updateSecretWithAlias(w io.Writer, name string) error {
	// name := "projects/my-project/secrets/my-secret"

	// Create the client.
	ctx := context.Background()
	client, err := secretmanager.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &secretmanagerpb.UpdateSecretRequest{
		Secret: &secretmanagerpb.Secret{
			Name: name,
			VersionAliases: map[string]int64{
				"test": 1,
			},
		},
		UpdateMask: &field_mask.FieldMask{
			Paths: []string{"version_aliases"},
		},
	}

	// Call the API.
	result, err := client.UpdateSecret(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to update secret: %w", err)
	}
	fmt.Fprintf(w, "Updated secret: %s\n", result.Name)
	return nil
}
```

### Java

To run this code, first [set up a Java development environment](https://docs.cloud.google.com/java/docs/setup.md.txt) and
[install the Secret Manager Java SDK](https://docs.cloud.google.com/secret-manager/docs/reference/libraries.md.txt#client-libraries-install-java).
On Compute Engine or GKE, you must
[authenticate with the cloud-platform scope](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes).

```java
import com.google.cloud.secretmanager.v1.Secret;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretName;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

public class UpdateSecretWithAlias {

  public static void updateSecret() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String secretId = "your-secret-id";
    updateSecret(projectId, secretId);
  }

  // Update an existing secret.
  public static void updateSecret(String projectId, String secretId) throws IOException {
    // 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 (SecretManagerServiceClient client = SecretManagerServiceClient.create()) {
      // Build the name.
      SecretName secretName = SecretName.of(projectId, secretId);

      // Build the updated secret.
      Secret.Builder secret =
          Secret.newBuilder()
              .setName(secretName.toString());
      secret.getMutableVersionAliases().put("test", 1L);      

      // Build the field mask.
      FieldMask fieldMask = FieldMaskUtil.fromString("version_aliases");

      // Update the secret.
      Secret updatedSecret = client.updateSecret(secret.build(), fieldMask);
      System.out.printf("Updated alias map: %s\n", updatedSecret.getVersionAliasesMap().toString());
    }
  }
}
```

### Node.js

To run this code, first [set up a Node.js development environment](https://docs.cloud.google.com/nodejs/docs/setup.md.txt) and
[install the Secret Manager Node.js SDK](https://docs.cloud.google.com/secret-manager/docs/reference/libraries.md.txt#client-libraries-install-nodejs).
On Compute Engine or GKE, you must
[authenticate with the cloud-platform scope](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes).

```javascript
/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const name = 'projects/my-project/secrets/my-secret';

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

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

async function updateSecret() {
  const [secret] = await client.updateSecret({
    secret: {
      name: name,
      versionAliases: {
        test: 1,
      },
    },
    updateMask: {
      paths: ['version_aliases'],
    },
  });

  console.info(`Updated secret ${secret.name}`);
}

updateSecret();
```

### PHP

To run this code, first learn about [using PHP on Google Cloud](https://docs.cloud.google.com/php/docs.md.txt) and
[install the Secret Manager PHP SDK](https://docs.cloud.google.com/secret-manager/docs/reference/libraries.md.txt#client-libraries-install-php).
On Compute Engine or GKE, you must
[authenticate with the cloud-platform scope](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes).

```php
// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\Secret;
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;
use Google\Cloud\SecretManager\V1\UpdateSecretRequest;
use Google\Protobuf\FieldMask;

/**
 * @param string $projectId Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $secretId  Your secret ID (e.g. 'my-secret')
 */
function update_secret_with_alias(string $projectId, string $secretId): void
{
    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient();

    // Build the resource name of the secret.
    $name = $client->secretName($projectId, $secretId);

    // Update the secret.
    $secret = (new Secret())
      ->setName($name)
      ->setVersionAliases(['test' => '1']);

    $updateMask = (new FieldMask())
      ->setPaths(['version_aliases']);

    // Build the request.
    $request = UpdateSecretRequest::build($secret, $updateMask);

    $response = $client->updateSecret($request);

    // Print the upated secret.
    printf('Updated secret: %s', $response->getName());
}
```

### Python

To run this code, first [set up a Python development environment](https://docs.cloud.google.com/python/docs/setup.md.txt) and
[install the Secret Manager Python SDK](https://docs.cloud.google.com/secret-manager/docs/reference/libraries.md.txt#client-libraries-install-python).
On Compute Engine or GKE, you must
[authenticate with the cloud-platform scope](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes).

```python
def update_secret_with_alias(
    project_id: str, secret_id: str
) -> secretmanager.UpdateSecretRequest:
    """
    Update the metadata about an existing secret.
    """

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

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Update the secret.
    secret = {"name": name, "version_aliases": {"test": 1}}
    update_mask = {"paths": ["version_aliases"]}
    response = client.update_secret(
        request={"secret": secret, "update_mask": update_mask}
    )

    # Print the new secret name.
    print(f"Updated secret: {response.name}")
```

### Ruby

To run this code, first [set up a Ruby development environment](https://docs.cloud.google.com/ruby/docs/setup.md.txt) and
[install the Secret Manager Ruby SDK](https://docs.cloud.google.com/secret-manager/docs/reference/libraries.md.txt#client-libraries-install-ruby).
On Compute Engine or GKE, you must
[authenticate with the cloud-platform scope](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes).

```ruby
# project_id = "YOUR-GOOGLE-CLOUD-PROJECT"  # (e.g. "my-project")
# secret_id  = "YOUR-SECRET-ID"             # (e.g. "my-secret")

# Require the Secret Manager client library.
require "google/cloud/secret_manager"

# Create a Secret Manager client.
client = Google::Cloud::SecretManager.secret_manager_service

# Build the resource name of the secret.
name = client.secret_path project: project_id, secret: secret_id

# Create the secret.
secret = client.update_secret(
  secret: {
    name: name,
    version_aliases: {
      test: 1
    }
  },
  update_mask: {
    paths: ["version_aliases"]
  }
)

# Print the updated secret name.
puts "Updated secret: #{secret.name}"
```

## What's next

- Learn how to [list secret versions and view secret version details](https://docs.cloud.google.com/secret-manager/docs/view-secret-version.md.txt).
- Learn how to [ensure data integrity](https://docs.cloud.google.com/secret-manager/docs/data-integrity.md.txt) when adding and accessing secret versions.