Traffic Policy Secrets
Secrets enable you to store sensitive data in encrypted vaults and reference them dynamically in your . This feature eliminates the need to hardcode passwords, API keys, and other sensitive values directly in policy YAML files. When you update a secret in a vault, it automatically rotates across all traffic policies that reference it, streamlining credential management.
Secrets are supported in all Traffic Policy actions and fields that support .
Secrets and vaults are currently in Developer Preview. Log into the ngrok dashboard to request access. During the Developer Preview, the following limitations apply:
- Secrets management is only available via the ngrok API (no dashboard UI)
- Secrets interpolated into certain actions may appear in cleartext in Traffic Inspector when full capture mode is enabled
- Secrets are only supported in the fields listed in the supported actions and fields section below
How it works
Vaults are secure containers that store your secrets. Each vault can contain multiple secrets, which are encrypted key-value pairs. Secrets are stored using AES-256 encryption at rest and transmitted over HTTPS with TLS 1.2+.
When you reference a secret in a Traffic Policy, the value is evaluated at runtime and never persisted in policy documents or logs. The ngrok API never returns secret values in response payloads.
Reference secrets in your Traffic Policy using the secrets.get() macro:
Loading…
The macro dynamically retrieves the secret value from the specified vault at runtime.
Using vaults and secrets
To use secrets, you'll need to create a vault to store them in.
Create a vault
Use the ngrok Agent CLI to create a vault:
Loading…
The response includes the vault ID, which you'll need when creating secrets within the vault:
Loading…
Create a secret
Create a secret within a vault using the vault ID:
Loading…
Common use cases for secrets
Basic authentication
Loading…
Webhook verification
Loading…
Audit events
Secrets and vaults emit the following audit events, all of which include the full resource details in the logs:
Vault events
| Event | Description |
|---|---|
vault_created.v0 | Triggered when a vault is created |
vault_deleted.v0 | Triggered when a vault is deleted |
vault_updated.v0 | Triggered when a vault is updated (name, description, metadata) |
Secret events
| Event | Description |
|---|---|
secret_created.v0 | Triggered when a secret is created |
secret_deleted.v0 | Triggered when a secret is deleted |
secret_updated.v0 | Triggered when a secret is updated |
Limits and pricing
Secrets and vaults are free to use during the Developer Preview phase. This feature will be billed and metered in the future, per the plan details below.
| Plan | Vault Limit | Secret Limit |
|---|---|---|
| Free | 5 (hard limit) | 5 total (hard limit) |
| Personal | 5 (hard limit) | 25 total (hard limit) |
| PayGo | 5 (soft limit, configurable) | 500 default (configurable) |
Please contact support to request higher limits than your plan provides, or to configure limits for the PayGo plan.