​

Ephemeral Proxy

​

When to use it

• The destination URL is dynamic — chosen per-request, not per-route.
• You want to detokenize vault tokens last-mile (PII handling, secret injection).
• You need a quick passthrough without configuring a Route, ApiKey scope, environment overrides, etc.

• You call the same upstream repeatedly and want signing, rate limits, env overrides, and full per-request observability.
• You need IP allowlisting, mTLS, or method-specific configuration.
• You want logs grouped by route in the dashboard.

​

How a request flows

Your client → POST https://api.knoxcall.com/v1/proxy
              X-Knox-Proxy-URL: https://api.stripe.com/v1/charges
              Authorization: Bearer kc_live_...
              Content-Type: application/json

              { "amount": 5000,
                "currency": "usd",
                "source": "{{ token: tok_01H... }}" }

KnoxCall:
  1. Authenticates your OAuth access token (or legacy API key)
  2. Checks `proxy:invoke` permission + your plan limit
  3. Validates the upstream URL (https only, DNS hostname, SSRF-safe)
  4. Scans body + query for {{ token: ... }} references
  5. Looks up each token in your vaults, gates per-vault detokenize
  6. Renders the body with raw values substituted in
  7. Sends the rewritten request to the upstream
  8. Streams the response back to you, audit-logged

Stripe sees:    { "amount": 5000, "currency": "usd",
                  "source": "tok_visa_real_card_token" }

You see:        Stripe's response, passed through unchanged.

​

Quick example

# 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... }}"
  }'

​

Template syntax

​

Required and optional headers

​

What you get back

​

Responses are re-tokenized

• Only the values this request opened, matched exactly. A different card number the processor happens to mention is your own data and is left alone; this is not a general card scan of your responses.
• Only pan vaults. A value from a generic, ssn or email vault echoed back is untouched.
• However the processor spelled it. 4111111111111111, 4111 1111 1111 1111, 4111-1111-1111-1111 and the form-encoded 4111+1111+1111+1111 / 4111%201111%201111%201111 all match.
• Body and headers. JSON fields (at any depth, including object keys and values sent as bare JSON numbers), form-encoded values, text bodies, and header values such as Location. A header value is replaced, never stripped, so a 3-D Secure redirect keeps working.

• A rewritten body is returned uncompressed. KnoxCall sends Accept-Encoding: identity upstream on any request that detokenizes a pan token, because a compressed reply cannot be scanned. If the upstream ignores that and compresses anyway, the response is withheld with 502 response_not_retokenizable rather than forwarded unscanned. The same answer is given for a binary body.
• Streaming is refused for these requests. A card number can straddle any chunk boundary the upstream picks, so a streamed reply cannot be re-tokenized honestly. A request that both detokenizes a pan token and asks for streaming (Accept: text/event-stream, or "stream": true in the body) is answered 409 pan_streaming_unsupported. Send the card request without streaming.

​

When a referenced token cannot be resolved

​

Raw card numbers are refused on egress

HTTP/1.1 403 Forbidden

{
  "error": {
    "type": "raw_pan_egress_refused",
    "message": "This request body contains what looks like a payment card number in the clear, and 'api.example-psp.com' is not allowed to receive raw card data. …"
  }
}

1. Tokenize the card and send the token — the intended path. Put the number in a vault whose token_format is pan and send {{ token: kcv_… }}. KnoxCall detokenizes it only toward that vault’s own allowed_destinations, so the number reaches your processor and nothing else. A value detokenized this way is never refused by this check.
2. Allow the destination — if a host genuinely must receive the number itself, an owner or admin replaces the workspace’s raw-card egress allowlist:
   PUT /admin/pan-egress/allowed-hosts
   Content-Type: application/json
   
   { "allowed_hosts": ["api.example-psp.com", "*.example-psp.com"] }
   
   Entries are bare hostnames or *.suffix wildcards — no scheme, port, path or IP literal. Adding a host requires a fresh second factor; removing one does not, because shutting the door is the lever you want reachable during an incident. On a configured Route there is a narrower option — the route’s Security tab grants raw-card egress for that route in that environment alone, without opening the destination to /v1/proxy, workflows or webhooks. See Routes. Every change is audited as egress.pan_allowed_hosts_updated with the previous list, so it can be reverted from the trail alone. The list is empty by default, which is why the refusal is what you see first. (There is no dashboard screen for this yet — the API is the surface.) The matching GET returns the list plus refused_this_month, so you can see how often the refusal has fired without trawling the audit log.

​

Limits and gates

​

Audit and observability

• An api_requests row with proxy_mode = 'ephemeral', status code, latency, upstream host, token count, and source IP. The body, headers, and token values are not stored.
• An audit_log entry tagged ephemeral_proxy.invoke, carrying retokenized_occurrences — how many echoed card numbers were replaced with their token on the way back (0 on every request that opened none).
• One vault.retokenize entry per vault whose card number the upstream echoed, with the occurrence count. The vault’s id is recorded; the number and the token never are.
• A Fleet Graph signal carrying (method, upstream_host, status_code, latency_ms) — never the body, never the token strings, never the customer’s path.

​

Comparison: Routes vs Ephemeral Proxy

​

Next steps

• See the Ephemeral Proxy API reference for the complete request/response schema.
• See Vaults to create the tokens you’ll reference.
• See Routes when you need a persistent, observable proxy instead.