> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/secrets/external-secrets/manage-secret-aliases/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Manage secret aliases

> Create and manage secret aliases to reference external secrets by a stable name in Itential Gateway automation.

Gateway 5.5+

A secret alias maps a logical name to a specific secret path within a secret provider. Automation references the alias name rather than the provider or path. If you change providers or rotate to a different secret path, update the alias—nothing else in your automation needs to change.

## Prerequisites

* At least one [secret provider configured](./configure-provider)

## Create a secret alias

```bash
iagctl create secret <alias-name> \
  --provider <provider-name> \
  --secret <secret-identifier>
```

When the secret value is a JSON object and you want to extract a specific field, add `--key`:

```bash
iagctl create secret <alias-name> \
  --provider <provider-name> \
  --secret <secret-identifier> \
  --key <field-name>
```

The format of `--secret` depends on the provider type:

* **Vault**: the path within the secrets mount, for example `myapp/creds`. The mount prefix from the provider's `--secrets-endpoint` is prepended automatically.
* **CyberArk**: `SafeName/ObjectName`, for example `ProdSafe/DB_Production_Password`.
* **Plugin**: passed as-is to the plugin subprocess.

**Example:** Create an alias called `db-password` that retrieves the `password` field from the Vault path `secret/data/my-app`:

```bash
iagctl create secret db-password \
  --provider my-vault \
  --secret secret/data/my-app \
  --key password
```

**Example:** Create an alias called `db-password` that retrieves a CyberArk-managed credential:

```bash
iagctl create secret db-password \
  --provider cyberark-prod \
  --secret "ProdSafe/DB_Production_Password"
```

## View secret aliases

List all aliases:

```bash
iagctl get secrets
```

View details for a specific alias:

```bash
iagctl describe secret <alias-name>
```

## Delete a secret alias

```bash
iagctl delete secret <alias-name>
```

Deleting an alias does not affect the underlying secret in the external provider.

## Reference a secret alias

Use the following syntax anywhere Gateway accepts a secret:

```
$GATEWAYSECRET_(alias-name)
```

The parentheses delimit the alias name for unambiguous parsing when embedded in strings.

### Code on Canvas

Reference a secret alias inline. The executing gateway resolves the alias at execution time:

```
$GATEWAYSECRET_(db-password)
```

### Inventory Manager

Set a device credential value to `$GATEWAYSECRET_(alias-name)`. The alias resolves each time a workflow runs against the device.

### Services and repositories

Alias names work anywhere Gateway accepts a secret name. See [Inject secrets into services](/itential-gateway/5/inject-secrets-into-services) for service injection syntax, and [Configure private repository access](/itential-gateway/5/configure-private-repository-access) and [Use SSH keys to clone git repositories](/itential-gateway/5/clone-git-repositories-ssh) for repository credential setup.

> Create and manage secret aliases to reference external secrets by a stable name in Itential Gateway automation.