> ## 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.

# Serve several domains

> Use your publishable key allowed origins to control which sites can collect through a Foil first-party integration, and serve several domains from one or more integrations.

Two settings decide where a first-party integration works. The publishable key's **allowed origins** decide which sites can start sessions. The integration decides which hostnames its edge answers on.

The default covers most sites:

1. Create one integration on the host your pages load from.
2. Leave **Serve every domain routed to this integration** on. It's on by default in the create form.
3. Add every host your pages load from to the publishable key's allowed origins, or add a `https://*.<domain>` wildcard such as `https://*.example.com`. Step 4 of the integration page checks the key for the wildcard and offers **Add to allowed origins** when it's missing.

Each page then loads the SDK from its own host, at the same path, and the allowed origins decide which of those hosts can start sessions.

## Allowed origins are the authority

Foil checks the browser's `Origin` header against the publishable key's allowed origins on every request, whether it arrives directly or through an integration. Each entry in the list is one of:

| Entry | Matches |
| - | - |
| `https://app.example.com` | That exact origin |
| `https://*.example.com` | `https://example.com` and any subdomain of it, over HTTPS on the default port |
| `*` | Any origin |

A key with no allowed origins accepts any origin. Test keys also accept `http://` and non-default-port origins, such as `http://localhost:3000`, for local development. Live keys accept only HTTPS origins on the default port. To change the list, open **API Keys** in the dashboard and edit the key's **Allowed origins**, one entry per line.

A request from an origin that isn't on the list fails with `403` and the error code `auth.origin_not_allowed`.

## What the site origin does

Every integration has one **site origin**, which the dashboard builds from **Domain** and **Subdomain**. It doesn't decide which sites can use the integration. Foil uses it for three things:

| Use | What Foil does with the site origin |
| - | - |
| Integration URL | The dashboard places the integration URL on the site origin's hostname, for example `https://www.example.com/foil` for `https://www.example.com`. |
| `Origin` fallback | Browsers omit the `Origin` header on some same-origin `GET` requests, such as the SDK's continuity request. For an integration that answers only on its own hostname, the edge then sends the site origin as `Origin`, so the key's allowed origins must include it. |
| Script CORS fallback | When a request for `t.js` arrives without an `Origin` header, Foil returns the site origin in `Access-Control-Allow-Origin`. |

The ownership TXT record proves control of the integration URL's hostname, not the site origin.

## Choose a layout

* Keep the default when one edge serves all of your hosts, such as one Cloudflare zone or one CloudFront distribution. Each page builds its integration URL from the host it loaded on, and you need only one TXT record.
* Turn serving every domain off when the integration should answer only on its own hostname. Pages on other hosts can still import `t.js` from that one integration URL. Those requests are cross-origin but same-site, Foil answers them with credentialed CORS responses, and every page that uses the URL shares one continuity cookie.
* Create one integration per host when your hosts sit behind different edges, such as two Cloudflare zones, or when each host should keep its own TXT record and continuity cookie. An organization can have up to 10 integrations.

With serving every domain on:

* The integration answers Foil's routes at the same path on every domain it reaches. What it reaches depends on the provider. See [Support by provider](#support-by-provider).
* When the browser omits `Origin`, the edge sends the origin of the domain the request arrived on instead of the site origin. See [Origin fallback](https://usefoil.com/docs/first-party/edge-contract.md#origin-fallback).
* The publishable key's allowed origins are the only control over which domains can start sessions. List each domain, use `https://*.<domain>` entries, or use `*`.
* The TXT record is still required, and only for the integration URL's hostname.

Each page builds its endpoint from the domain it loaded on. The dashboard's install snippet does this for you:

```javascript theme={"dark"}
const endpoint = location.origin + "/foil";
const foil = await import(endpoint + "/t.js").then((Foil) =>
  Foil.start({
    publishableKey: "pk_live_your_publishable_key",
    endpoint,
  }),
);
```

You can turn the setting on or off later in the **Domains** section of the integration page. See [Change the domains an integration serves](https://usefoil.com/docs/first-party/manage.md#change-the-domains-an-integration-serves).

## Support by provider

| Deployment | Serving every domain off | Serving every domain on |
| - | - | - |
| Cloudflare, deployed by Foil | The integration hostname. The Worker route is `<hostname>/<path>/*`. | Every hostname in the integration's Cloudflare zone, apex included, through the route `*<zone>/<path>/*`. Sites in other zones need their own integration. |
| Cloudflare, your Worker | The integration hostname. On other domains, the module passes requests to your own handler. | Every domain your Worker routes to the integration path |
| AWS CloudFront, deployed by Foil | Every alternate domain name on the distribution reaches the integration, because cache behaviors match on path alone, but the `Origin` fallback is the site origin for all of them. | Every alternate domain name on the distribution, with the domain each request arrived on as the `Origin` fallback |
| Custom proxy | The integration hostname. Your edge refuses other domains. | Every domain your edge routes to the integration path |

When you put several CloudFront integrations on one distribution, give each a different path. CloudFront matches cache behaviors on path alone, and Foil refuses to install an integration whose behaviors overlap existing ones.


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