Using Vaults & Secrets with Traffic Policy

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 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")

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. 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"

The response includes the vault ID, which you’ll need when creating secrets within the vault:

{
  "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 currently free to use. 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.

How ngrok handles

Traffic Policy Features

Examples

Using Vaults & Secrets with Traffic Policy

How it works

Using vaults and secrets

Create a vault

Create a secret

Common use cases for secrets

Basic authentication

Webhook verification

Audit events

Vault events

Secret events

Limits and pricing

​How it works

​Using vaults and secrets

​Create a vault

​Create a secret

​Common use cases for secrets

​Basic authentication

​Webhook verification

​Audit events

​Vault events

​Secret events

​Limits and pricing

How it works

Using vaults and secrets

Create a vault

Create a secret

Common use cases for secrets

Basic authentication

Webhook verification

Audit events

Vault events

Secret events

Limits and pricing