> ## Documentation Index
> Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# First-party integrations

> Serve the Foil browser SDK and its collection requests from your own domain through your CDN, and learn what an integration changes and what it leaves alone.

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.

> [!NOTE]
>
> 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:

| Name | Example | What it is |
| - | - | - |
| **Site origin** | `https://www.example.com` | The origin your pages load from |
| **Integration URL** | `https://www.example.com/foil` | The HTTPS URL and path where Foil's routes live, on the site origin's hostname. The SDK's `endpoint` option takes it. |

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](https://usefoil.com/docs/first-party/deployments.md).

## 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](#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](https://usefoil.com/docs/content-security-policy.md#first-party-integrations).
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:

```html theme={"dark"}
<link rel="modulepreload" href="https://www.example.com/foil/t.js" crossorigin>
<script type="module">
  const foil = await import("https://www.example.com/foil/t.js").then((Foil) =>
    Foil.start({
      publishableKey: "pk_live_your_publishable_key",
      endpoint: "https://www.example.com/foil",
    }),
  );
</script>
```

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](https://usefoil.com/docs/first-party/multiple-domains.md).

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](https://usefoil.com/docs/browser-sdk.md#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](https://usefoil.com/docs/browser-sdk.md) 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](https://usefoil.com/docs/first-party/multiple-domains.md).

## Continuity cookie

Through an integration, Foil keeps visitor continuity in a cookie on your own domain:

| Attribute | Value |
| - | - |
| Name | `__Secure-foil-cid-<integration ID>` |
| Flags | `Secure; HttpOnly; SameSite=None` |
| Flags on the partitioned copy | `Secure; HttpOnly; SameSite=None; Partitioned` |
| Domain | None. The cookie is host-only, so sibling subdomains don't share it. |
| Path | The integration path followed by `/`, for example `/foil/`, or `/` when the integration has no path |
| Lifetime | `Max-Age=34560000` (400 days) |

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

* [Choose a deployment](https://usefoil.com/docs/first-party/deployments.md) and set up the integration.
* [Serve several domains](https://usefoil.com/docs/first-party/multiple-domains.md) from one or more integrations.
* [Run your own edge](https://usefoil.com/docs/first-party/edge-contract.md) on any CDN with the custom edge contract.
* [Read the checks](https://usefoil.com/docs/first-party/checks.md) and fix a failing one.
* [Manage an integration](https://usefoil.com/docs/first-party/manage.md): domains, credentials, SDK releases, and removal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.