Skip to main content
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: 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: 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.
  • 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.
  • 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:
You can turn the setting on or off later in the Domains section of the integration page. See Change the domains an integration serves.

Support by provider

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.