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
| 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 |
Quick start
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
}'
POST above) is forwarded as-is. KnoxCall will:
- Read the target URL from the
X-Knox-Proxy-URL header.
- Resolve
{{ token: ... }} references in the body or query string against your Vaults (detokenizes, audits the read).
- Validate the URL: HTTPS only, hostname must resolve, IP must not be private/metadata.
- Make the call through KnoxCall’s egress (static IP if you’ve configured one).
- Stream the response back verbatim — same status code, same headers (minus hop-by-hop), same body bytes.
- 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
| 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 |
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.
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
