Secrets enable you to store sensitive data in encrypted vaults and reference them dynamically in your traffic policies.
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 CEL.
Secrets and vaults are currently in Open Beta.
During the Open Beta, 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
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:
secrets.get("vault-name", "secret-name")
Using vaults and secrets
To use secrets, you’ll need to create a vault to store them in. REST APIs are provided on the ngrok service for both Vaults and Secrets.
Create a vault
Use the ngrok Agent CLI to create a vault:
ngrok api vaults create --name "my-vault" --description "Description of vault purpose"
{
"id": "vault_2yNPzuk6GjHrx3mlOCkJK42RsdR",
"name": "my-vault",
"description": "Description of vault purpose",
"created_at": "2025-08-01T21:10:37Z",
"uri": "https://api.ngrok.com/vaults/vault_2yNPzuk6GjHrx3mlOCkJK42RsdR"
}
Create a secret
Create a secret within a vault using the vault ID:
ngrok api secrets create \
--name "my-secret" \
--value "secret-value" \
--vault-id "vault_2yNPzuk6GjHrx3mlOCkJK42RsdR" \
--description "Optional description"
Common use cases for secrets
Basic authentication
on_http_request:
- actions:
- type: basic-auth
config:
credentials:
- "user123:${secrets.get('my-vault', 'password')}"
Webhook verification
on_http_request:
- actions:
- type: verify-webhook
config:
provider: github
secret: "${secrets.get('webhooks-vault', 'github-secret')}"
Audit events
Secrets and vaults emit the following audit events, all of which include the full resource details in the logs:
Vault events
| Log | 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
| Log | 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 and Open Beta 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) |
| Hobbyist | 5 (hard limit) | 25 total (hard limit) |
| PayGo | 5 (configurable) | 500 default (configurable) |
Please contact support to configure limits for the PayGo plan. 
