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, Host and Content-Length headers, Cookie, and any header beginning with X-Knox-. Three more groups are never forwarded. Each name is matched exactly, in any letter case; apart from X-Knox- there is no prefix rule:

The control headers KnoxCall reads itself: X-KnoxCall-Key, X-KnoxCall-Route, X-KnoxCall-Environment, X-KnoxCall-Signature, X-KnoxCall-Agent-Id, X-KnoxCall-Agent-Token, X-KnoxCall-Client-Assertion, X-KnoxCall-Origin and X-KnoxCall-Env.
The headers a reverse proxy adds to describe the connection to KnoxCall rather than your request: X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto and X-Forwarded-Server, X-Real-IP, True-Client-IP, X-Client-Cert-Verify, X-Client-Cert-Thumbprint and X-Client-Cert-Subject.
The request headers Cloudflare adds: CF-Connecting-IP, CF-Ray, CF-IPCountry and the rest of the exact names in Request headers KnoxCall does not forward, which is the complete list.

A header that only resembles one of these is yours and is forwarded. That includes the CF-Access-Client-Id / CF-Access-Client-Secret pair and the cf-access-token header for an upstream behind Cloudflare Access.

Your KnoxCall credential is never forwarded. Authorization and Cookie are always dropped, and X-Api-Key is dropped whenever it holds a KnoxCall credential (a value beginning tk_, kc_, kr_ or AKE) — that is the key you authenticated to KnoxCall with, and sending it on would put a key granting your whole management API into your upstream’s access logs.An X-Api-Key carrying your upstream’s own key — sk-ant-… for Anthropic, and so on — is forwarded unchanged, so providers that authenticate with this header keep working.

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	`token_expired`	A `{{ token: ... }}` reference names a token that exists but whose TTL has passed. Distinct from `token_not_found` so a lapsed TTL does not read as a token you never created. Nothing is substituted and nothing is sent upstream.
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.
403	`insufficient_scope`	The OAuth access token was deliberately narrowed and its grant does not include `proxy:invoke`. Applies to every HTTP method — see Permissions.
409	`pan_streaming_unsupported`	The request references a token from a `pan` vault and asks for a streamed response (`Accept: text/event-stream`, or `"stream": true` in the body). A streamed reply cannot be re-tokenized — a card number can straddle any chunk boundary the upstream picks — so the combination is refused rather than served unprotected. Send the card request without streaming. See Responses are re-tokenized.
502	`response_not_retokenizable`	The request detokenized a `pan` token and the upstream’s reply could not be scanned for the card number — it came back compressed (KnoxCall sends `Accept-Encoding: identity` on these requests; this one was ignored) or binary. The reply was withheld rather than forwarded unscanned. Do not blindly retry — the upstream call already happened.
500	`internal_error`	A plan-limit lookup or token-resolution step failed internally — including a vault that cannot be opened (a key or KMS fault). The request is refused; the still-unresolved template is never forwarded.
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). If it exists but has expired, the request fails with 400 token_expired. In every refusal the template is left unresolved and the upstream is not called — a token reference that cannot be opened never travels as itself.

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

OAuth scope

These evaluate what the credential may do. If you call with an OAuth access token whose client was deliberately narrowed, a separate check evaluates what that token may do, and it requires proxy:invoke (or proxy:*) — on every HTTP method, because one handler serves them all and a bodyless GET spends an escrowed credential exactly as a POST does. proxy:read and proxy:write do not satisfy it: escrowing a credential is not permission to spend it. A refused call returns 403 insufficient_scope, naming the scope in the WWW-Authenticate header and the body. API keys and un-narrowed tokens carry no grant to enforce and are unaffected.

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

Workload Identity

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

OAuth scope

Audit

​Invoke

​Request Headers

​Request Body

​Response

​Errors

​Templates

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

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

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

​Permissions

​OAuth scope

​Audit

Invoke

Request Headers

Request Body

Response

Errors

Templates

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

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

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

Permissions

OAuth scope

Audit