Invoke Ephemeral Proxy

The Ephemeral Proxy is a single endpoint — ANY /v1/proxy — that accepts any HTTP method and forwards the request to the URL you supply in the X-Knox-Proxy-URL header. References of the form {{ token: ... }} in the body or query string are resolved against your tenant’s vaults before the request reaches the upstream. For a conceptual overview see the Ephemeral Proxy guide.

Unlike the Routes endpoints — which manage proxy configuration — this endpoint executes a one-shot proxy call. There is no id to look up, no row to list, and no environment overrides.

Invoke

ANY /v1/proxy

Forwards the request to the URL in X-Knox-Proxy-URL. Body and query-string {{ token: ... }} references are resolved against your tenant’s vaults before the upstream call is made. The upstream response is streamed back unchanged.

Request Headers

Header	Required	Description
`Authorization`	Yes	`Bearer $TOKEN` — a minted `kc_` OAuth access token (see Authentication). Legacy `tk_` / `AKE` API keys are also accepted as Bearer on this endpoint.
`X-Knox-Proxy-URL`	Yes	The upstream URL. Must be `https://`, must use a DNS hostname (no IP literals), must pass SSRF validation.
`Content-Type`	No	Defaults to `application/json` if omitted. Non-JSON bodies are sent as-is for string content.
`X-Knox-Encrypted`	No	Base64-encoded JSON payload addressable from templates via `{{ encrypted \| json: $.path }}`. v1 is opaque base64-JSON; full JWE support is on the roadmap.
`X-Knox-Timeout-Ms`	No	Per-request upstream timeout. Positive integer ≤ `30000`. Defaults to `25000`.

All other headers you send are forwarded to the upstream except for hop-by-hop headers (Connection, Keep-Alive, TE, Trailers, Transfer-Encoding, Upgrade, Proxy-Authorization, Proxy-Authenticate), the Authorization and Host headers, and any header beginning with X-Knox-.

Request Body

Optional. Sent to the upstream after token substitution. The body is scanned recursively for two template forms:

Template	Resolves to
`{{ token: tok_xxx }}`	The raw value stored under token `tok_xxx` in any of your tenant’s vaults.
`{{ encrypted \| json: $.path }}`	The value at JSONPath `$.path` inside the decoded `X-Knox-Encrypted` payload.
`\{{ ... }}`	An escape — renders a literal `{{ ... }}` and is never resolved.

Anything else shaped like {{ ... }} is rejected with 400 template_error rather than forwarded to the upstream. See Templates. Maximum 20 distinct token references per request.

Response

The upstream’s response is streamed back unchanged: same status code, same headers (minus hop-by-hop and Content-Length), same body bytes. KnoxCall adds two correlation headers:

Response Header	Description
`X-Knox-Request-Id`	The KnoxCall request ID. Use it to look up the audit log entry.
`X-Knox-Destination-Status`	The upstream’s status code, echoed in case an intermediate CDN rewrites it.

# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

curl -X POST https://api.knoxcall.com/v1/proxy \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Knox-Proxy-URL: https://api.stripe.com/v1/charges" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "usd",
    "source": "{{ token: tok_01HZX... }}"
  }'

import os
import requests

# KNOXCALL_ACCESS_TOKEN is a minted OAuth access token — see /api-reference/authentication
resp = requests.post(
    "https://api.knoxcall.com/v1/proxy",
    headers={
        "Authorization": "Bearer " + os.environ["KNOXCALL_ACCESS_TOKEN"],
        "X-Knox-Proxy-URL": "https://api.stripe.com/v1/charges",
        "Content-Type": "application/json",
    },
    json={
        "amount": 5000,
        "currency": "usd",
        "source": "{{ token: tok_01HZX... }}",
    },
)
print(resp.status_code, resp.headers["X-Knox-Request-Id"])
print(resp.json())

// KNOXCALL_ACCESS_TOKEN is a minted OAuth access token — see /api-reference/authentication
const resp = await fetch("https://api.knoxcall.com/v1/proxy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KNOXCALL_ACCESS_TOKEN}`,
    "X-Knox-Proxy-URL": "https://api.stripe.com/v1/charges",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 5000,
    currency: "usd",
    source: "{{ token: tok_01HZX... }}",
  }),
});

console.log(resp.status, resp.headers.get("X-Knox-Request-Id"));
console.log(await resp.json());

Errors

Status	Type	Description
400	`validation_error`	Missing or malformed `X-Knox-Proxy-URL`, invalid `X-Knox-Timeout-Ms`, malformed `X-Knox-Encrypted`, or more than 20 token references.
400	`token_not_found`	A `{{ token: ... }}` reference does not exist in any of your tenant’s vaults.
400	`template_error`	A template expression failed to render (malformed JSONPath, missing key in encrypted payload), or is not one of the supported forms — e.g. `{{ secret: x }}`, `{{ token: }}`, or a mis-cased `{{ TOKEN: ... }}`. Escape it as `\{{` if the braces are meant for the upstream.
402	`plan_limit`	Ephemeral Proxy requires the Starter plan or above.
403	`forbidden`	The upstream URL failed SSRF validation (private IP range, metadata endpoint, non-HTTPS, etc.).
403	`PolicyDenied`	RBAC denial — either the `ephemeral_proxy:invoke` gate or the per-token `vault:detokenize` gate denied the request.
500	`internal_error`	A plan-limit lookup or token-resolution step failed internally.
502	`upstream_error`	The upstream did not respond, returned an unrecoverable transport error, or timed out.

Templates

`{{ token: <token-id> }}`

Substituted with the raw value of the matching vault token. Tokens are tenant-globally unique — you do not need to specify the vault.

{
  "card_number": "{{ token: tok_01HZX0M... }}",
  "exp_month": 12
}

If the token doesn’t exist in any of your tenant’s vaults, the request fails with 400 token_not_found. If the token exists but you lack vault:detokenize permission for the vault that owns it, the request fails with 403 (PolicyDenied).

`{{ encrypted | json: $.path }}`

Reads a value from the decoded X-Knox-Encrypted payload using JSONPath. Useful when you want to keep ad-hoc sensitive values out of your application’s heap.

# Encode the payload your application would otherwise put directly in the body
PAYLOAD=$(echo -n '{"customer_id":"cus_123","cvc":"492"}' | base64)

# $TOKEN is a minted OAuth access token — see /api-reference/authentication
curl -X POST https://api.knoxcall.com/v1/proxy \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Knox-Proxy-URL: https://api.stripe.com/v1/payment_methods" \
  -H "X-Knox-Encrypted: $PAYLOAD" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "{{ encrypted | json: $.customer_id }}",
    "card": { "cvc": "{{ encrypted | json: $.cvc }}" }
  }'

In v1 the payload is opaque base64-encoded JSON; full JWE with per-tenant frontend keypairs is on the roadmap.

`\{{ ... }}` — sending literal braces

Any {{ ... }} that is not one of the two forms above is rejected with 400 template_error. It is never forwarded. That is deliberate: silently passing an unrendered {{ token: ... }} through would disclose the token identifier to the third-party upstream and deliver a request with a hole where a credential should be. When the braces are meant for the upstream’s own templating, escape the opening delimiter with a backslash. The escape renders a literal {{, and the text after it is never treated as a template — so a single body can carry both:

{
  "card_number": "{{ token: tok_01HZX0M... }}",
  "email_subject": "Hi \\{{ first_name }}, your receipt"
}

The upstream receives card_number substituted with the real value, and email_subject as the literal Hi {{ first_name }}, your receipt. Note the doubled backslash: JSON has no \{ escape, so a literal backslash is written \\ in the source. Only the opening {{ is escapable — a bare }} was never a delimiter and always passes through untouched, so nested JSON such as {"a":{"b":{"c":1}}}} is never rewritten. To bypass templating entirely and forward your bytes verbatim, send X-Knox-Proxy-Mode: transparent instead.

Permissions

Each invocation evaluates two permissions:

Resource	Action	When evaluated
`ephemeral_proxy`	`invoke`	Once per request, before URL validation.
`vault`	`detokenize`	Per token reference, scoped to the vault that owns the token.

The vault:detokenize check is enforced per token reference, scoped to the vault that owns the token. A denial throws PolicyDenied and the request fails with 403.

Audit

Every invocation writes:

An api_requests row with proxy_mode = 'ephemeral', status code, latency, upstream host, source IP, and token count. The body, headers, and resolved token values are never stored.
An audit_logs entry tagged ephemeral_proxy.invoke (Audit Logs).
A Fleet Graph signal carrying method, upstream host, status code, and latency. The customer’s path is recorded as /proxy — never the raw upstream path.

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

Invoke

Request Headers

Request Body

Response

Errors

Templates

`{{ token: <token-id> }}`

`{{ encrypted | json: $.path }}`

`\{{ ... }}` — sending literal braces

Permissions

Audit

​Invoke

​Request Headers

​Request Body

​Response

​Errors

​Templates

​{{ token: <token-id> }}

​{{ encrypted | json: $.path }}

​\{{ ... }} — sending literal braces

​Permissions

​Audit

Invoke

Request Headers

Request Body

Response

Errors

Templates

`{{ token: <token-id> }}`

`{{ encrypted | json: $.path }}`

`\{{ ... }}` — sending literal braces

Permissions

Audit