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, create a variable that references its value with the secrets.get() macro, then use that variable  in your policy.

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:

Because the secret macro is not supported on all traffic policy actions and configuration variables, we recommend you use a workaround where you first fetch your secret into a variable with set-vars, and then use it across your policy.

For example, if your OAuth implementation requires a client_secret, you can now store that in a vault that's fetched into a variable, then into your action.

on_http_request:
  - actions:
      - type: set-vars
        config:
          vars:
            - oauth_client_secret: ${secrets.get('my-vault', 'oauth_client_secret')}
      - type: oauth
        config:
          provider: google
          client_id: $CLIENT_ID
          client_secret: ${vars.oauth_client_secret}

The same concept applies to any secret and any Traffic Policy action.

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:

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

Share this post
API gateway
Authentication
Compliance
Features
Security
Production