Usage

API key (per caller)

Created in the console as `corx_<random>` and stored only as a SHA-256 hash — the raw value is shown once. A key can carry allowed origins, a per-minute rate limit, a cache TTL, keyless grants, allowed hosts, SSRF-check opt-outs and upstream injection. Send it in any of the forms below.

Keyless origin grants

Enable keyless access on a key and browsers from its allowed origins call the proxy without carrying the key at all. The grant matches the `Origin` header (or the `Referer`'s origin for same-origin GETs) and is metered per visitor IP, so one embedded site cannot drain the key. Origins are canonicalized on save (lowercase host, default port dropped), and the one wildcard form is a loopback port — `http://localhost:*` covers any localhost port, so a dev server on a random port needs a single entry. Host wildcards (`https://*.example.com`) and regexes are rejected. An origin is a convenience, not a credential — scripts can forge it — so pair it with allowed hosts and a rate limit.

Public tier

A hosted instance may publish a shared key on its landing page. It is deliberately reduced: GET and HEAD only, daily quotas per calling site / per target host / per instance, no cache control, no injection and no subdomain mode; `Cookie` and `Authorization` are stripped before forwarding. Fine for public data, demos and prototypes.

Where the key goes — and where it must not

Server-side only. A key in a browser bundle, a public repository or a page source is a key you have given away; a site that needs to call the proxy from a browser should use a keyless origin grant (or the public key, if the data really is public). Never send credentials or personal data through a shared instance at all.

How a credential is attached

Variables (`NAME=value`) hold the values; header and query rules use them. An `@host` line scopes the rules below it, so one key can carry a different credential per upstream — including the usual shape, the same header name with a different value per host (`Authorization` for two vendors). Header rules set or remove request headers (`Authorization: Bearer ${VENDOR_KEY}`, `!X-Debug`); query rules do the same with URL parameters (`api_key = ${VENDOR_KEY}`) for APIs that authenticate that way. Rules always win over what the caller sent, so a browser cannot spoof an injected header, and which rule applies is decided by the target host, not by the caller.

Letting the caller reference a variable

Exposure is per variable — `client: true` on the Admin API, the **Client-referencable variables** field in the console — and it names the hosts the caller may reference it toward. A caller then writes `${VENDOR_KEY}` in a header or query param of its own request; the proxy substitutes the value before forwarding. The caller only ever learns the name it wrote, never the value, and a variable you do not expose stays invisible to it.

Two scopes, and both must allow the host

A rule's `@hosts` says where *that rule* applies; a variable's own hosts say where *that variable* may ever resolve. The second bounds the first: a rule that could resolve a scoped variable toward another host is rejected at save time — including a key-level rule, because it can reach every allowed host. Patterns are the same everywhere: an exact host, `*.suffix` (label boundary), or `*`, so `*.vendor.com` covers `api.vendor.com` and nothing covers the apex `vendor.com` implicitly. Client references are evaluated per redirect hop, so a variable scoped to one host does not resolve after a redirect to another.

Order, and what happens when nothing matches

On the way out, caller references resolve first and the key's rules run afterwards, removes before sets. A rule therefore always beats what the caller asked for — `!X-Debug` deletes it, a `set` replaces it — so a browser cannot spoof an injected header. Anything the proxy will not resolve (unknown name, private variable, host outside the scope) is forwarded exactly as written. That keeps the feature additive (a key with no exposed variable behaves exactly as before) and makes an unexposed name indistinguishable from a nonexistent one, so callers cannot probe what a key holds. Headers CORX owns — a corx-shaped `X-Api-Key`, `X-Admin-Token` and the hop-by-hop set — are dropped before anything resolves; a non-corx `X-Api-Key` (including a `${VAR}` reference) is the caller's own upstream credential and is forwarded. A vendor requiring one of these names (Anthropic's `x-api-key`) is therefore covered either way: BYOK from a trusted server, or a rule when the browser must never hold the secret.

One key, three upstreams

The console's key page edits the variables as rows (each with a Client toggle and a host scope) next to the Header / Query / Response rules fields and the allowed-hosts field; the Admin API takes them as `vars` (with `client` and `hosts` per variable), `headerRules`, `paramRules`, `responseRules` and `allowedHosts`.

OPENAI_KEY=sk-…
ANTHROPIC_KEY=sk-ant-…
VENDOR_KEY=vendor-…

@api.vendor.com
VENDOR_KEY

@api.openai.com
Authorization: Bearer ${OPENAI_KEY}
@api.anthropic.com
x-api-key: ${ANTHROPIC_KEY}
@api.vendor.com
Authorization: Bearer ${VENDOR_KEY}

api.openai.com, api.anthropic.com, api.vendor.com

Every `@host` must fall inside the allowed-hosts list, and the list is mandatory once anything is injected — that is the guard that stops a caller from pointing your credential at a host of their choosing. A rule outside the list is never attached.

What a caller's reference becomes

For the example above: `VENDOR_KEY` is exposed for `api.vendor.com` only, `PRIVATE_KEY` is not exposed, and a header rule sets `Authorization` for `api.vendor.com`.

What it is for

The common case is one front end calling several providers — an LLM at one vendor, payments or maps at others — each with its own key and no secret in the page. It also covers an API that authenticates with a query parameter instead of a header, and the same upstream with different keys per environment (one key per environment, or a variable per deployment). With client references the page can even choose which of several credentials to use without ever holding one — the pattern a browser-side app needs once it talks to more than one provider.

One key or several

Everything above puts every upstream in a single key — one allowed-hosts union, one rate limit and one allowed-origins list shared by all of them, and one secret store to rotate. Split into one key per upstream when you want separate limits or origins, when a leak should reach only one vendor, or when the same host needs different credentials on different paths (rules are scoped by host, not by path). Keyless access grants an origin exactly one key, so a page that calls several upstreams without carrying a key gets all of them from that key's rules — and, for the variables you exposed, can reference them.

Cache and safety

Secrets are encrypted at rest when `INJECTION_KEK` is set, masked everywhere they are read (console, logs, playground preview), and the request log stores the pre-injection URL. A key with header rules never reads or writes the R2 cache, because its responses are key-specific, while a key that injects only query parameters still caches under the effective URL. A key with any client-referencable variable does not use the shared cache at all: the reference is caller-supplied and a redirect can resolve it on a later hop, so no response through that key can be proven free of a secret. The public tier cannot inject at all — it is GET/HEAD only — so upstream credentials mean a self-hosted instance and a standard key. Treat an exposed variable as public to anyone who can call the key.

Cache markers

`X-Corx-Cache` is the header to watch while debugging: `MISS` means upstream answered (the response is stored only when it is cacheable), `HIT` means R2 answered. `X-Corx-Target` names the upstream host, and `X-Corx-Latency-Ms` is the time the proxy spent.

TTL

The deployment's default TTL applies unless `?corx-ttl=` lowers or raises it, up to the cap. A key can pin its own default TTL, or `0` to never store; the public tier cannot set a TTL at all.

What bypasses the cache

Always bypassing the shared cache: non-GET/HEAD methods, requests carrying `Authorization` or `Cookie`, `?corx-no-cache=1`, JSONP (`corx-callback`), Range requests, and keys that inject upstream headers. Keys with response header rules do cache — their resolved rules are part of the cache key, so a rewritten response is never served to another key.