Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

LogDescription
vault_created.v0Triggered when a vault is created
vault_deleted.v0Triggered when a vault is deleted
vault_updated.v0Triggered when a vault is updated (name, description, metadata)

​
Secret events

LogDescription
secret_created.v0Triggered when a secret is created
secret_deleted.v0Triggered when a secret is deleted
secret_updated.v0Triggered 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.
PlanVault LimitSecret Limit
Free5 (hard limit)5 total (hard limit)
Hobbyist5 (hard limit)25 total (hard limit)
PayGo5 (configurable)500 default (configurable)
Please contact support to configure limits for the PayGo plan.