DocumentationBuild. Deploy. Operate.
DocsQSCSCore HTTP API

Headers & CORS

On this page 10 sections

HTTP header reference

Headers are conditional: not every core response or upstream passthrough includes QSCS diagnostics. Names are HTTP headers; values below describe the current implementation. Ignore unknown diagnostic values safely and use status plus Content-Type to handle the response.

Client request headers

HeaderValue / purpose
X-QSCS-Client-UuidClient identifier, conventionally 32 lowercase hex characters. Identifies the key binding; not authentication by itself.
X-QSCS-TsUnix milliseconds as decimal digits.
X-QSCS-NonceFresh 16-byte random nonce encoded as 32 lowercase hex characters.
X-QSCS-SigBase64 Ed25519 signature over the canonical request. See signing reference.
X-QSCS-DeltaDecoder capability: 1 for legacy deltas, 2 for JSON byte-delta support. Omit without a compatible decoder.
X-QSCS-Base-HashFNV-1a 32-bit hash of the exact retained baseline bytes, encoded as eight lowercase hex digits. Scoped to the requested URL and client.
X-QSCS-Base-KeyLegacy input; current client-delta baseline selection does not use it for cross-URL reconstruction.
X-QSCS-Stream1 requests API Boost streaming on the same signed GET.
X-QSCS-Stream-Delta2 opts into stream delta frames; requires a compatible decoder.
X-QSCS-Stream-BaseRetained stream payload’s SHA-256 as 64 lowercase hex characters. Different algorithm from X-QSCS-Base-Hash.
X-QSCS-Browser-Navigation1 is used by the packaged navigation worker; not needed by a normal API client.

Response headers

HeaderMeaning / availability
X-QSCS-ModeDelivery diagnostic. See values below; absence is valid on some routes.
X-QSCS-Encodingbase64 for encoded client delta bodies.
X-QSCS-Payload-BytesLogical complete payload size when emitted.
X-QSCS-Wire-BytesPath-specific transfer accounting. Negotiated client deltas report transferred delta/body bytes; some cache/peer paths report upstream or substrate bytes saved even while sending a full body to the caller. It is not a universal HTTP download-size counter.
X-QSCS-Origin-Stateunchanged indicates an origin comparison; the current response may still contain a complete body.
X-QSCS-CacheHIT, PERSISTED or PEER on relevant cache paths.
X-QSCS-Cache-Modeapi-boost, until-invalidated or timed on federated cache hits.
X-QSCS-Cache-AgeSaved response age in seconds on API Boost hits.
X-QSCS-TTL-RemainingRemaining configured reuse time in seconds on timed hits.
X-QSCS-Stream1 on an API event stream. Event payloads carry their own ids; stream bytes are not ordinary response-delta frames.
X-QSCS-Headless-ReasonFallback or outage reason; see HEADLESS response table.
X-QSCS-Headless-AgeSeconds since the fallback cache entry’s refresh, where emitted.
X-QSCS-Headless-Sessiondegraded on listener fallback responses; not a session token and not emitted on every fallback path.
X-QSCS-Browser-Navigationon or off for processed HTML navigation policy.
X-QSCS-Browser-Cacheeligible or bypass for processed HTML navigation baselines.

Mode values

ValueInterpretation
fullFull representation.
incrementalDelta processing occurred; use content type/encoding to distinguish a client delta from a reconstructed full body.
nochangeUnchanged state. On a negotiated client response with an empty body, reuse the verified baseline.
hitTimed cache response.
persistedPersistCache response.
peerpullState recovered from a peer.
federated-identity-hitAccount-partitioned cache hit; further client negotiation may replace this mode.
negcacheNegative-cache response, such as a cached 404.
passthroughLive/bypass path or application-specific unavailable response.
headlessOrigin fallback; check HTTP status and reason.

Verified headers sent to your backend

HTTP — verified upstream context

X-QSCS-Identity: <client UUID>
X-QSCS-Authenticated-Subject: account:42
X-QSCS-Identity-Issuer: app.example.com

QSCS removes client-supplied copies on its proxy path before adding verified values. Accept them only through restricted QSCS ingress. Resolve the subject and enforce account status and permissions in your backend. These are upstream authorization context, not credentials for a client to set.

Inspect a response

Shell / curl — response headers

curl -sS -D - -o /dev/null 'https://app.example.com/'

For browser JavaScript, the edge must expose headers the client reads; see Headers & CORS. X-QSCS-Reconstructed: 1 is added by the browser adapter to its reconstructed Response and is not a core wire header.

Browser CORS contract

CORS is enforced by browsers and is independent of backend language. Native and server clients still need valid authentication even though they do not enforce browser CORS. A successful preflight neither authenticates a caller nor confirms that the target application endpoint exists.

OPTIONS /{path}

Authentication: none. Body: none. Core answers before origin routing without calling the backend. The public proxy may intercept OPTIONS or replace its response.

HTTP request

OPTIONS /api/report HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: GET
Access-Control-Request-Headers: x-qscs-client-uuid,x-qscs-ts,x-qscs-nonce,x-qscs-sig

Default core response — selected headers

HTTP/1.1 200 OK
Content-Length: 0
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Cache-Control, Content-Type, X-QSCS-Client-Uuid, X-QSCS-Ts, X-QSCS-Nonce, X-QSCS-Sig, X-QSCS-Delta, X-QSCS-Base-Hash, X-QSCS-Stream, X-QSCS-Stream-Delta, X-QSCS-Stream-Base
Access-Control-Expose-Headers: X-QSCS-Mode, X-QSCS-Encoding, X-QSCS-Wire-Bytes, X-QSCS-Payload-Bytes, X-QSCS-Cache
Access-Control-Max-Age: 86400

Response policy and proxy configuration

Core applies its default CORS policy on normal listener/proxy paths. API stream responses expose X-QSCS-Stream. Not every early error or runtime-asset response has the same header set, so verify the actual public response.

  1. Choose one CORS policy at the public edge and avoid duplicate or conflicting Allow-Origin values.
  2. Preserve the signature, delta and stream request headers shown above.
  3. Expose X-QSCS-Stream for browser streaming. Add X-QSCS-Cache-Mode, X-QSCS-Cache-Age, X-QSCS-TTL-Remaining or outage diagnostics if your application reads them.
  4. For conditional status reads, allow If-None-Match and expose ETag; they are not in the default lists above.
  5. For cookies, configure an explicit allowed origin and credential policy. A wildcard Allow-Origin does not permit credentialed browser reads. The packaged signed API client uses credentials omitted.
  6. Keep origin authentication and backend access restrictions in place. CORS is not an authorization mechanism.

The default preflight does not advertise arbitrary application headers such as Authorization, or unsupported write methods. Configure required application headers explicitly at the edge; adding a method to CORS does not add daemon support for that method.

Check the public preflight

Shell / curl

curl -i -X OPTIONS 'https://api.example.com/api/report' \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: GET' \
  -H 'Access-Control-Request-Headers: x-qscs-client-uuid,x-qscs-ts,x-qscs-nonce,x-qscs-sig'

Also inspect the actual GET, including its error responses. curl displays the headers but does not enforce browser CORS.

Need a hand with your deployment?Contact support ↗Back to top ↑