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

# Using Vaults & Secrets with Traffic Policy

> Store sensitive data in encrypted vaults and reference them dynamically in your Traffic Policies.

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.

<Info>
  Secrets interpolated into certain actions may appear in cleartext in Traffic Inspector when full capture mode is enabled
</Info>

## 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:

```yaml theme={null}
secrets.get("vault-name", "secret-name")
```

The [macro](/traffic-policy/macros/#secretsgetstring-string---string) 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](/api-reference/vaults/list) and [Secrets](/api-reference/secrets/list).

### Create a vault

Use the ngrok Agent CLI to create a vault:

```shell theme={null}
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:

```json theme={null}
{
  "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:

```shell theme={null}
ngrok api secrets create \
  --name "my-secret" \
  --value "secret-value" \
  --vault-id "vault_2yNPzuk6GjHrx3mlOCkJK42RsdR" \
  --description "Optional description"
```

## Common use cases for secrets

### Basic authentication

```yaml theme={null}
on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - "user123:${secrets.get('my-vault', 'password')}"
```

### Webhook verification

```yaml theme={null}
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](/obs/events/reference/#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

<Warning>
  Secrets and vaults are currently free to use.
  **This feature *will* be billed and metered in the future, per the plan details below**.
</Warning>

| 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](mailto:support@ngrok.com) to configure limits for the PayGo plan.