Skip to main content
A first-party integration serves the Foil browser SDK and its collection requests from your own domain instead of 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.
Foil can deploy the edge for you on Cloudflare or AWS CloudFront. You can also run it yourself, in a Cloudflare Worker you already operate or on any other CDN or reverse proxy. See Choose a deployment.

Load the SDK from your domain

Step 4 of the integration page, Add Foil to your pages, covers three things in this order:
  1. 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.
  2. If your site sets a Content Security Policy, add the script-src and connect-src lines the page shows next to the install snippet. See Content Security Policy.
  3. Copy the install snippet into the <head> of each page that starts Foil. It preloads t.js from the integration URL, imports it, passes the same URL as endpoint, and uses the key you picked.
For an integration URL of https://www.example.com/foil, the snippet looks like this:
When the integration serves every domain routed to it, which is the default, the snippet builds the integration URL from the page’s own origin instead. See Serve several domains. The 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 enabled pk_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. 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 DNT and Sec-GPC, so Foil observes them as it does for direct requests.
  • Human verification. verifyHuman() always loads from cdn.usefoil.com and talks to api.usefoil.com directly, even when the SDK loads through an integration. Your edge doesn’t need to forward it.
  • Direct loading. Pages that import t.js from cdn.usefoil.com keep working. You can move pages to the integration one at a time.

Next steps