Decouple policy from sensitive data: introducing Secrets for Traffic Policy

Today we’re shipping a major upgrade to how you manage sensitive data in your traffic policies with the developer preview of Secrets for Traffic Policy.

Traffic Policy configuration often includes sensitive values, like passwords or API keys. Previously, you needed to embed those values directly in cleartext which is a security and compliance risk. Now using Secrets, you instead store sensitive values in secure, encrypted vaults and reference them from your Traffic Policy. No more hardcoded secrets directly in your policy YAML.

ngrok api vaults create --name "my-vault"
ngrok api secrets create --name "password" --value "hunter2" --vault-id="vault_1234"

To use the secret, reference it with the secrets.get() macro:

on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - "alan:${secrets.get('my-vault', 'password')}"

Why secrets?

Secrets help you improve the overall security posture of your traffic policies and enable easier reuse and rotation for sensitive values that would otherwise appear in your traffic policies.

With Secrets for Traffic Policy secrets, sensitive strings are:

• Stored securely in a vault and referenced dynamically via macros.
• Encrypted at rest using industry-standard AES-256 and in-transit with HTTPS + TLS 1.2.
• Evaluated at runtime, never persisted in policy documents or logs.

Secrets have benefits beyond just security. By managing secrets through a centralized vault, you can reference them across multiple policies and endpoints—meaning a single update to a secret in the vault automatically propagates to every policy that uses it. This eliminates the need for repetitive edits, reduces the risk of errors, and ensures consistency across all of your endpoints.

Developer preview limitations

During the Developer Preview, there are a couple limitations on Secrets support. As we approach General Availability, we’ll continue to expand our support and remove limitations. The important limitations to be aware of are:

• Secrets are only configurable via API; there is no dashboard UI yet.
• Secrets you interpolate into certain actions, like add-headers, might appear in cleartext in Traffic Inspector if you have full capture mode enabled.
• Secrets are only supported directly on a subset of Traffic Policy fields:
  • set-vars: vars
  • verify-webhook: secret
  • basic-auth: credentials
  • restrict-ips
    • allow
    • deny
  • jwt-validation
    • issuer.allow_list[*].value
    • http.tokens[*].name
    • http.tokens[*].prefix
    • jws.keys[*].sources[*].additional_jkus

Get started with Secrets for Traffic Policy

Secrets are in developer preview, which means you'll need to request access, and we'll let you know when we've activated it for your account. Developer preview participants get early, free access to features in exchange for sharing their experience with ngrok’s product team.

Get started with the documentation:

• Security Macros
• CLI + Vaults
• CLI + Secrets
• REST + Vaults
• REST + Secrets

And if you have questions or feedback, join the conversation on Discord!