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

# External secrets overview

> Connect Itential Gateway to external secrets managers so credentials are retrieved at runtime rather than stored locally.

Gateway 5.5+

Itential Gateway can retrieve credentials directly from external secrets managers at runtime. Instead of storing credentials in the gateway, you configure a **secret provider** that connects to your secrets manager and create **secret aliases** that give each secret a stable name in your automation.

## How it works

A secret provider stores the connection and authentication settings for your external secrets manager. A secret alias maps a name you choose to a specific secret path within that provider.

Your automation references the alias name. If you change secrets managers or move a secret to a new path, you update the alias. Nothing else in your automation changes.

## Reference syntax

Use the following syntax to reference a secret alias in your automation:

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

**Example:** Reference a database password stored in Vault:

```
postgresql://user:$GATEWAYSECRET_(db-password)@db.example.com/myapp
```

## Supported providers

| Provider                                             | Authentication method                                    |
| ---------------------------------------------------- | -------------------------------------------------------- |
| HashiCorp Vault (KV Secrets Engine v2), token auth   | Static token file on the gateway server                  |
| HashiCorp Vault (KV Secrets Engine v2), AppRole auth | Role ID and secret ID files with automatic token refresh |
| CyberArk Central Credential Provider (CCP)           | Mutual TLS with certificate and private key files        |
| Custom plugin                                        | Any external source; you supply the retrieval logic      |

## Where you can use secrets

You can use secret aliases in two ways depending on how your automation runs.

**Running automation directly on Gateway** — Use `$GATEWAYSECRET_(alias-name)` anywhere the gateway accepts a secret:

| Context         | How to reference                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| Code on Canvas  | Add `$GATEWAYSECRET_(alias)` inline; the gateway retrieves the secret when the canvas runs                   |
| Task decorators | Pass the alias name as the secret value; the gateway injects it as an environment variable at execution time |

**Running automation from Itential Platform** — When Platform initiates automation on a connected gateway, Platform can send a `$GATEWAYSECRET_(alias-name)` variable instead of a resolved credential. The gateway retrieves the credential locally from its configured provider and uses it for the task. The credential is never sent back to Platform.

This lets you use an on-premises secrets manager with a SaaS Platform deployment without requiring a VPN connection between Platform and your secrets manager.

| Context                              | How to reference                                                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Inventory Manager device credentials | Set the credential to `$GATEWAYSECRET_(alias-name)`; the gateway resolves it each time a workflow runs against the device |
| Gateway-executed integrations        | Include `$GATEWAYSECRET_(alias-name)` in the integration payload; the gateway resolves it before executing                |
| Built-in gateway services            | Device broker, send config, and send command support `$GATEWAYSECRET_(alias-name)` credentials                            |

External secrets configuration is available via the iagctl CLI or via Gateway database import/export. Gateway Manager UI-based configuration will be available in a future release.

## Logging

Gateway logs the alias name, provider name, and success or failure for each secret retrieval. Secret values are never written to logs.

## Next steps

* [Configure a secret provider](./configure-provider)
* [Configure a custom plugin provider](./configure-custom-plugin-provider)
* [Manage secret aliases](./manage-secret-aliases)