1.3.0.
Configuration values
In step 2 of the integration page, select Reveal proxy config. The dashboard asks you to verify your identity, then shows these values:
Copy config JSON copies the same values in the form Foil’s adapters read, where
collectionBase is the integration URL and pageOrigin is the site origin:
"anyOrigin": true. Ignore fields you don’t use. The JSON never contains the credential.
Handle a request
For each request your edge receives:- Decide whether the request belongs to Foil. See Match the request. If it doesn’t, pass it to your application unchanged.
- Build the upstream headers from the forwarded headers, the continuity cookie, and the headers your edge sets.
- Send the request to
https://api.usefoil.comfollowed by the path with the integration prefix removed and the original query string, with the same method and body. See Send the request upstream. - Return Foil’s response to the browser. See Return the response.
Match the request
A request belongs to Foil when all of these are true:- Its origin equals the integration URL’s origin, for example
https://www.example.com. An integration that serves every domain routed to the edge skips this check. - Its path starts with the integration URL’s path followed by
/, for example/foil/. An integration without a path matches from/. - After you remove that prefix, the method and remaining path match a row in the following table.
<release>, <session>, <document>, and <id> each consist of 1 to 128 letters, digits, -, or _, and <release> has at least 8. A path that contains %, \, or // never matches. Match complete paths only. Don’t forward a whole /v2/ prefix.
For example, POST https://www.example.com/foil/v2/collect/sessions?x=1 goes upstream as POST https://api.usefoil.com/v2/collect/sessions?x=1.
Forwarded headers
Copy only these request headers from the browser, with their values unchanged. Foil reads several of them during scoring, includingAccept-Encoding and the client hints, so don’t normalize or rewrite them. Drop every other header.
On the two script routes, don’t forward
authorization.
Don’t forward Signature, Signature-Input, or Signature-Agent under their own names. Your edge sends them as X-Foil-Proxy-Signature, X-Foil-Proxy-Signature-Input, and X-Foil-Proxy-Signature-Agent. See Signed agents.
Continuity cookie
From the browser’sCookie header, forward only cookies named __Secure-foil-cid-<integration ID>. A browser can hold more than one, so forward each of them, joined with ; , and let Foil pick the one whose signature verifies. Never forward your application’s cookies, and don’t send a Cookie header on the script routes.
Headers your edge sets
Any request that carries an
X-Foil-Proxy-* header must prove it with a valid credential for an installed integration. Foil doesn’t fall back to treating it as an ordinary request.
Origin fallback
When the integration URL is on the page’s own origin, browsers omit theOrigin header on same-origin GET requests, including the SDK’s continuity request to /v2/collect/r. Foil checks every request against the publishable key’s allowed origins, so it needs an origin to compare.
When the browser sent no Origin, set it to:
- The integration’s Site origin, for an integration that answers only on its own hostname.
- The origin of the hostname the request arrived on, such as
https://shop.example.net, for an integration that serves every domain routed to the edge.
Origin header the browser sent.
Signed agents
Some AI agents sign each request with Web Bot Auth, which uses HTTP Message Signatures (RFC 9421). When Foil verifies a signature, the session is attributed to the agent that signed it. The signature covers the URL the agent called on your edge, so Foil checks it against that URL rather than the one your edge forwards to:- Host. The value of
X-Foil-Proxy-Host. It must be the integration URL’s host or another host on the same registrable domain, such ascdn.example.comfor the integration URLhttps://www.example.com/foil. Only when your edge sends noX-Foil-Proxy-Host, or a value that isn’t a hostname on port 443, does Foil use the integration URL’s host instead. - Path. The integration URL’s path followed by the path your edge forwarded. For example, a request forwarded to
/v2/collect/sessionsfor the integration URLhttps://www.example.com/foilwas called as/foil/v2/collect/sessions. - Query and scheme. The forwarded query string, and
https. - Headers. The values your edge forwarded. A signature can cover only the forwarded headers and the three signature headers.
X-Foil-Proxy-Signature headers on a request with a valid credential, and ignores Signature, Signature-Input, and Signature-Agent on any request from an edge. A Foil release that can’t verify signatures through an edge drops the X-Foil-Proxy-* headers, so it records the signature as absent rather than invalid.
Foil reports a signature as unverifiable (error) rather than invalid when it can’t rebuild what the agent signed:
X-Foil-Proxy-Hostnames a host on another registrable domain than the integration URL’s. Foil doesn’t fall back to the integration URL’s host in this case.- The signature covers a header your edge doesn’t forward, such as
Cookie. - Your edge sent no
X-Foil-Proxy-Host, and the signature doesn’t verify for the integration URL’s host. The agent may have called another hostname your edge serves.
Managed-AllViewer and Managed-AllViewerExceptHostHeader both include the three signature headers, but only Managed-AllViewer includes Host. With Managed-AllViewer, your function must still set Host to api.usefoil.com before the request goes upstream.
Send the request upstream
- Use HTTPS to
api.usefoil.comand pass the request body through unchanged forPOST. - Don’t follow redirects. If Foil answers with a
3xxstatus other than304, return502to the browser instead. - Don’t cache requests or responses for Foil’s routes at your edge.
- Set a timeout. Foil’s adapters wait 15 seconds, then return
502withCache-Control: no-store.
Return the response
Return Foil’s status, headers, and body unchanged, includingSet-Cookie, the CORS headers, and Cache-Control.
- Caching. Foil sends
CDN-Cache-Control: no-storeon every response through an integration.t.jshas a short browser cache lifetime, and the continuity response has a private one, but neither may be stored in a shared cache. The upstream URLhttps://api.usefoil.com/t.jsis the same for every integration, so a cache keyed on it can serve one integration’s release to another. - Compression. If your edge’s HTTP client decompresses the upstream response, remove
Content-EncodingandContent-Lengthbefore you return it. - Errors. If the upstream request fails or times out, return
502withCache-Control: no-store.
Rejections
Foil rejects a request from an edge with401 and the error code auth.invalid_api_key when any of these is true:
- The credential or integration ID is wrong, or the credential has been retired.
- You haven’t selected Start accepting traffic yet, or the integration is being removed or has been removed.
- The method and path aren’t a route in the table.
- The path names an SDK release that Foil doesn’t list.
Hostisn’tapi.usefoil.com.X-Foil-Proxy-Viewer-IPis missing or isn’t a single IP address.
401 when the publishable key belongs to the integration’s other environment, such as a pk_test_* key on a Live integration. Otherwise, a 401 for a request that carries a valid publishable key means one of the edge problems above.
Credential rotation
A rotation gives the integration a second credential while the first stays valid. To start one, select Rotate in the Proxy credential section of the integration page. While a rotation is open:- Foil accepts both credentials. Reveal proxy config shows the new one.
- You deploy the new credential to your edge whenever you’re ready. Foil records which credential each request carries.
- Foil retires the old credential once all of these are true:
- At least an hour has passed since the rotation started.
- The new credential has arrived through your edge.
- The old credential hasn’t arrived for an hour, or a day has passed since the new one first arrived.
Run inside an existing Cloudflare Worker
If your site is served by a Cloudflare Worker you already operate, create a Cloudflare integration and choose Your Worker under Who deploys it. Step 2 of the integration page then gives you a Worker module that implements this contract with your integration’s values filled in. It exportsfoilProxy(request, env), which returns a response for Foil’s routes and null for anything else.
-
Save the module as
foil-proxy.jsnext to your Worker. -
Select Reveal proxy config and store the credential as a Worker secret:
-
Call the module first in your
fetchhandler: - Deploy your Worker, then select Start accepting traffic in step 3.
CF-Connecting-IP and returns 404 for requests that arrive from another Worker.
Test your edge
After you select Start accepting traffic, request the SDK through the integration URL:200 and no Set-Cookie header. Before you select Start accepting traffic, the same request returns 401. Then load a page that runs the install snippet, reload it once, and confirm all three checks pass.