cdn.usefoil.com and api.usefoil.com. Your CDN answers a fixed set of Foil routes under a path you choose, such as https://www.example.com/foil, and forwards them to Foil. Session scoring, your publishable and secret keys, and server-side verification work the same way they do for a direct integration.
First-party integrations are in early access and are enabled per organization. If Integrations doesn’t appear in the dashboard navigation, contact Foil to enable it. Only owners and admins can create or change an integration, and the dashboard asks you to verify your identity before each sensitive change.
How a request flows
Each integration has two URLs:
Your CDN answers only Foil’s routes under the integration URL’s path and forwards them to Foil. Every other path on your site is unchanged.
1
The page loads the SDK from your domain
Your page imports
t.js from the integration URL. Your CDN forwards the request, and Foil returns the current SDK release.2
The SDK collects through the same URL
The SDK sends session, batch, result, and continuity requests to routes under the integration URL.
3
Your edge forwards each request to Foil
The edge sends the request to
api.usefoil.com with three extra headers: the integration’s proxy credential, the integration ID, and the visitor’s IP address as your CDN observed it. It forwards only an allowlisted set of request headers and none of your application’s cookies.4
Foil handles it like a direct request
Foil verifies the proxy credential, then authenticates the publishable key, checks the key’s allowed origins, and scores the session as it would for a direct request.
Load the SDK from your domain
Step 4 of the integration page, Add Foil to your pages, covers three things in this order:- Pick a publishable key in the integration’s environment. The page shows whether the key’s allowed origins cover the site origin, or the
https://*.<domain>wildcard when the integration serves every domain, and offers Add to allowed origins when they don’t. See Keys and environments. - If your site sets a Content Security Policy, add the
script-srcandconnect-srclines the page shows next to the install snippet. See Content Security Policy. - Copy the install snippet into the
<head>of each page that starts Foil. It preloadst.jsfrom the integration URL, imports it, passes the same URL asendpoint, and uses the key you picked.
https://www.example.com/foil, the snippet looks like this:
modulepreload link starts downloading t.js while the page is still parsing, and the import then uses the preloaded module. When the integration serves every domain, the link uses the path alone, such as /foil/t.js, which resolves to the same URL that the snippet builds from location.origin. A path resolves against the page’s base URL, so on a page whose <base> element points at another origin, write the link with the page’s own origin instead, such as https://www.example.com/foil/t.js. If you write your own loader instead, preload the exact URL it imports. See Preload the SDK.
endpoint is the base URL the SDK sends collection requests to. When you import t.js from the integration URL, the SDK derives endpoint from the script’s directory, so https://www.example.com/foil/t.js implies https://www.example.com/foil and you can leave the option out. Set it explicitly when you bundle the SDK into your own JavaScript or load it from any other path, because the SDK can then infer only your site’s origin, not the integration path.
The value must be an HTTPS URL without credentials, a query string, or a fragment, and its path can contain only letters, digits, -, _, and /. A relative value such as /foil resolves against the page’s URL. An invalid value makes start() reject with config.validation_failed, and calling start() again on the same page with a different endpoint rejects with config.already_initialized. The client that start() returns exposes the resolved value as foil.endpoint.
Everything else about the SDK stays the same. See Browser SDK for endpoint and the rest of the API.
Keys and environments
Each integration belongs to one environment. A Test integration accepts only enabledpk_test_* publishable keys from your organization, and a Live integration accepts only enabled pk_live_* keys. Foil rejects requests that use a key from another organization or the other environment.
The publishable key’s allowed origins still decide which sites can start sessions. Requests that pass through an integration are checked against the same list as direct requests, so the list must include the integration’s site origin, or a https://*.<domain> wildcard when the integration serves every domain routed to it. See Serve several domains.
Continuity cookie
Through an integration, Foil keeps visitor continuity in a cookie on your own domain:
The value is a signed token scoped to your organization. Your edge forwards only this cookie to Foil and never your application’s cookies, and Foil never sets a cookie on
t.js responses. Browsers still apply their own limits to cookie lifetime and storage, so the cookie improves continuity without guaranteeing it.
Foil sets the cookie twice with the same token: once unpartitioned, with the value prefixed by x., and once as a partitioned copy. Browsers that support partitioned cookies store the two separately, and a top-level page sends both.
When your page runs the SDK inside a cross-site iframe, the browser always sends the partitioned copy, which is scoped to the top-level site that embeds the frame. It also sends the unpartitioned cookie when it allows third-party cookies, as Chrome and Edge do by default. Because that cookie is the same on every site that embeds your frame, Foil can recognize one browser across those sites. The unpartitioned cookie only names a candidate visitor: Foil still requires a compatible fingerprint before it links a session to that visitor. A browser that doesn’t support partitioned cookies keeps only the partitioned copy’s value, as a single SameSite=None cookie.
Network edge probe
Your CDN terminates the visitor’s TLS connection, so Foil can’t observe the browser’s own TLS and HTTP/2 handshake through an integration. The SDK measures it with the network edge probe, a short request that goes directly from the browser to Foil’s probe hosts and never passes through your CDN. The probe runs on a per-session subdomain of Foil’s probe zone,*.e2.usefoil.com.
When the probe succeeds, Foil uses its measurement for the checks that compare the browser’s TLS and HTTP/2 fingerprints with its user agent, the same as it does for direct traffic. Admission never depends on the probe. When the probe is blocked or fails, Foil records the session’s network as unverified, and the session still loads, collects, and scores.
If your site sets a Content Security Policy, keep https://*.e2.usefoil.com in connect-src so the probe can connect. Running the probe on a subdomain of your own domain is coming soon.
What doesn’t change
- Server-side verification. Sealed tokens, the Sessions API, and webhooks work the same way. Your backend doesn’t need to know whether a session came through an integration.
- Keys. You keep using the same publishable and secret keys.
- Privacy signals. The edge forwards
DNTandSec-GPC, so Foil observes them as it does for direct requests. - Human verification.
verifyHuman()always loads fromcdn.usefoil.comand talks toapi.usefoil.comdirectly, even when the SDK loads through an integration. Your edge doesn’t need to forward it. - Direct loading. Pages that import
t.jsfromcdn.usefoil.comkeep working. You can move pages to the integration one at a time.
Next steps
- Choose a deployment and set up the integration.
- Serve several domains from one or more integrations.
- Run your own edge on any CDN with the custom edge contract.
- Read the checks and fix a failing one.
- Manage an integration: domains, credentials, SDK releases, and removal.