Skip to main content

​
Ephemeral Proxy overview

KnoxCall’s Ephemeral Proxy lets you proxy any HTTPS request through KnoxCall without registering a Route 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

​
How it differs from Routes

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

​
Quick start

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 (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 instead. See the Invoke reference Templates section for the full spec.

​
Plan limits

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