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.

## 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. On the **Secret Manager** page, click the **Regional secrets** tab.

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

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

5. Do the following:

   1. Specify the alias name.

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

6. 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">LOCATION</var>: the Google Cloud [location](https://docs.cloud.google.com/secret-manager/docs/locations.md.txt) 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 --location=LOCATION \
  --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 --location=LOCATION `
  --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 --location=LOCATION ^
  --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">LOCATION</var>: the Google Cloud [location](https://docs.cloud.google.com/secret-manager/docs/locations.md.txt) of the secret.
- <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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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"
  }
}
```

### 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/api/option"
	"google.golang.org/genproto/protobuf/field_mask"
)

// updateSecret updates the alias map on an existing secret.
func UpdateRegionalSecretWithAlias(w io.Writer, projectId, locationId, secretId string) error {
	// name := "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()

	name := fmt.Sprintf("projects/%s/locations/%s/secrets/%s", projectId, locationId, secretId)

	// 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 regional secret: %w", err)
	}
	fmt.Fprintf(w, "Updated regional 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.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretName;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

public class UpdateRegionalSecretWithAlias {

  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 to update.
    String secretId = "your-secret-id";
    updateRegionalSecretWithAlias(projectId, locationId, secretId);
  }

  // Update an existing secret using an alias.
  public static Secret updateRegionalSecretWithAlias(
      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 name.
      SecretName secretName = 
          SecretName.ofProjectLocationSecretName(projectId, locationId, 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());

      return updatedSecret;
    }
  }
}
```

### 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 projectId = 'my-project';
// const locationId = 'my-location';
// const secretId = 'my-secret';

const name = `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 updateRegionalSecret() {
  const [secret] = await client.updateSecret({
    secret: {
      name: name,
      versionAliases: {
        test: 1,
      },
    },
    updateMask: {
      paths: ['version_aliases'],
    },
  });

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

updateRegionalSecret();
```

## What's next

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