> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ephemeral Proxy overview

> Proxy any HTTPS request through KnoxCall without registering a Route first. Useful for ad-hoc API calls, agent runtimes, and one-shot integrations that don't justify a permanent Route.

# Ephemeral Proxy overview

KnoxCall's **Ephemeral Proxy** lets you proxy any HTTPS request through KnoxCall without registering a [Route](/essentials/routes/what-are-routes) first. Pass the target URL in the `X-Knox-Proxy-URL` header and send your payload as the request body; KnoxCall resolves any Vault token references, makes the request, and streams the response back verbatim.

Think of it as Routes' lower-friction cousin: same proxy core (secrets injection, egress controls, audit) without the upfront configuration step.

## Why use it

| Problem                                                                        | Without ephemeral                                                 | With ephemeral                                     |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- | -------------------------------------------------- |
| Agent runtime needs to call an arbitrary URL once                              | Pre-register every URL it might hit (impossible)                  | One-shot proxy with the same secrets + audit story |
| Internal script needs to call an API, but not enough volume to deserve a Route | Either register it (config noise) or call it directly (audit gap) | Use ephemeral; gets logged like any Route call     |
| Testing a new integration before committing to it                              | Build a Route, throw it away after                                | Ephemeral; nothing to clean up                     |
| Multi-tenant SaaS where each tenant's URLs are unknown ahead of time           | Can't pre-register                                                | Ephemeral handles unknown URLs at runtime          |

## How it differs from Routes

|               | Routes                                                   | Ephemeral                                         |
| ------------- | -------------------------------------------------------- | ------------------------------------------------- |
| **Setup**     | Register the URL, method, secrets, environment overrides | None — pass everything per-call                   |
| **API path**  | `/proxy/{route_name}`                                    | `/v1/proxy`                                       |
| **URL**       | Fixed at registration                                    | Per-call                                          |
| **Secrets**   | Reference by name (configured on the Route)              | Reference by name (looked up per-call)            |
| **Audit row** | `proxy_mode='route'`                                     | `proxy_mode='ephemeral'` (filterable in API Logs) |
| **Best for**  | Integrations you call repeatedly with stable config      | One-off calls, agent runtimes, ad-hoc work        |

The shared infrastructure (secrets, egress allowlist, rate limits, SSRF guard) applies to **both**.

## Quick start

```bash theme={"dark"}
curl -X POST https://api.knoxcall.com/v1/proxy \
  -H "Authorization: Bearer $KC_API_KEY" \
  -H "X-Knox-Proxy-URL: https://api.example.com/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "{{ token: tok_J8K2M4N5P6Q7R8 }}",
    "amount": 4999
  }'
```

The HTTP method you use (`POST` above) is forwarded as-is. KnoxCall will:

1. **Read the target URL** from the `X-Knox-Proxy-URL` header.
2. **Resolve `{{ token: ... }}`** references in the body or query string against your [Vaults](/essentials/vaults/overview) (detokenizes, audits the read).
3. **Validate the URL**: HTTPS only, hostname must resolve, IP must not be private/metadata.
4. **Make the call** through KnoxCall's egress (static IP if you've configured one).
5. **Stream the response back** verbatim — same status code, same headers (minus hop-by-hop), same body bytes.
6. **Audit** with `proxy_mode='ephemeral'` so you can filter the calls in API Logs.

## Templating

Template expressions in the **request body** and **query string** are resolved before the call is forwarded:

* `{{ token: <token-id> }}` — detokenize from a Vault. Token ids are tenant-globally unique, so you don't qualify them with a vault name. Audited per-token.
* `{{ encrypted | json: $.path }}` — reads a value at the given JSONPath out of the base64-encoded JSON you pass in the `X-Knox-Encrypted` request header and substitutes it into the body/query.

**Headers are not templated** — the template engine does not process `{{ ... }}` expressions in headers in v1. To inject a secret into an outbound `Authorization` header, use a [Route](/essentials/routes/what-are-routes) instead.

See the [Invoke reference](/api-reference/ephemeral-proxy/invoke) Templates section for the full spec.

## Plan limits

| Tier       | Enabled | Ops/mo    | RPS limit | Tokens per request |
| ---------- | ------- | --------- | --------- | ------------------ |
| Free       | no      | 0         | 0         | 20                 |
| Starter    | yes     | 100k      | 10        | 20                 |
| Pro        | yes     | 1M        | 100       | 20                 |
| Enterprise | yes     | unlimited | unlimited | 100                |

<Note>The per-request token cap in the table reflects plan config (Enterprise = 100). In v1 the handler enforces a fixed cap of **20 tokens per request** across all plans; the per-plan Enterprise value is not yet wired into the handler.</Note>

The Free tier is **off by default** because the unbounded "any URL with API-key" surface is the most-abused KnoxCall capability. Enterprise tenants who only want pre-configured Routes can override to `false` even on a paid plan.

## Security

* **HTTPS only**. Plain HTTP is rejected.
* **SSRF guard**: hostname must resolve to a public IP. Private (RFC1918), link-local, loopback, and metadata IPs (`169.254.169.254`) are blocked.
* **Tenant scoping**: secrets and Vault tokens are scoped to your tenant; ephemeral calls can't reference other tenants' material.
* **Audit**: every call hits API Logs with `proxy_mode='ephemeral'`.

## Next steps

* [Routes overview →](/essentials/routes/what-are-routes) — for repeated calls with stable config
* [Vaults →](/essentials/vaults/overview) — what `{{ token: ... }}` references
* [Secrets →](/essentials/secrets/secrets-overview) — what `{{ secret: ... }}` references