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

# Pin a browser SDK release

> Load one exact release of the Foil browser SDK with its integrity hash, and move to newer releases on your own schedule, for example after a 24-hour delay.

`https://cdn.usefoil.com/t.js` always serves Foil's latest release. If you want to decide when a new release reaches your pages, for example only after it has been public for 24 hours, load one release at its own address with its integrity hash instead, and move to newer releases from your deploy process.

When you finish, your pages load one exact release of the SDK, the browser refuses any other bytes under that address, and you control when the release changes.

## How releases work

Every release of the browser SDK is published at its own address, `https://cdn.usefoil.com/t.<id>.js`. The file at that address never changes, and Foil keeps it available at least until the release's `accepted_until` time, which is at least 90 days after Foil last published the release.

To pin a release, you load its address and give the browser its Subresource Integrity (SRI) hash. Foil's API lists the releases you can pin, with their hashes.

> [!NOTE]
>
> Pin with the `integrity` hash, not the `id` in the file name. The `id` names the release but does not prove what the file contains; the hash does. The values on this page are examples. Always take `script_url` and `integrity` from the API.

Pages that load Foil through a [first-party integration](https://usefoil.com/docs/first-party/overview.md) pin the same way, with the release served from your integration URL. See [Pin through a first-party integration](#pin-through-a-first-party-integration).

## Before you begin

* Create a live secret key with the `sdk_releases:read` scope. In the dashboard, open **API Keys**, select **New secret key**, choose **Custom**, select **List SDK releases** under **SDK releases**, and select **Create key**. A key with **All scopes** also works. The **Recommended** scopes do not include it.
* Keep the key in your server or deploy pipeline. It is a secret key, so never send it to the browser.
* If your site sets a Content Security Policy, the `script-src` source you already allow for Foil (`https://cdn.usefoil.com`) covers the pinned release's file. The import map you add in [Load the pinned release](#load-the-pinned-release) is an inline script, though, so your policy must allow it separately. See [Content Security Policy](https://usefoil.com/docs/content-security-policy.md).

## List the releases you can pin

```bash theme={"dark"}
curl https://api.usefoil.com/v1/sdks/web/releases \
  -H "Authorization: Bearer $FOIL_SECRET_KEY"
```

The response lists releases newest first:

```json theme={"dark"}
{
  "data": [
    {
      "object": "sdk_release",
      "id": "7c1e4b0a9f3d2e6c8b5a4f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c",
      "sdk": "web",
      "version": "0.1.0",
      "script_url": "https://cdn.usefoil.com/t.7c1e4b0a9f3d2e6c8b5a4f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c.js",
      "integrity": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC",
      "published_at": "2026-11-10T00:59:12.000Z",
      "accepted_until": "2027-02-08T00:59:12.000Z",
      "current": true,
      "rolled_back": false
    }
  ],
  "pagination": { "limit": 1, "has_more": false },
  "meta": { "request_id": "req_3f8c2a91d4b7460e9a1c5d2e7f0b6a48" }
}
```

| Field | Description |
| - | - |
| `id` | The release's identifier, also the name of its file. |
| `version` | The SDK version the release reports. |
| `script_url` | The release's address. The file at this address never changes. |
| `integrity` | The SRI hash of the file at `script_url`. Foil records it from the release build after confirming the CDN serves exactly those bytes. |
| `published_at` | When the release first went out. |
| `accepted_until` | Foil accepts sessions from this release, and keeps its file available, at least until this time. |
| `current` | Whether this is the release `t.js` serves now. |
| `rolled_back` | Whether Foil rolled back from this release to an earlier one. Do not move to a rolled-back release. |

The list holds every release Foil still accepts sessions from, so it is never paged. It starts with the releases published after Foil began recording integrity hashes in November 2026.

## Choose a release

Pick the newest release that has been public long enough for your policy and that Foil has not rolled back. Releases come newest first, so the first match is the one you want. For a 24-hour delay:

```js theme={"dark"}
const response = await fetch("https://api.usefoil.com/v1/sdks/web/releases", {
  headers: { Authorization: `Bearer ${process.env.FOIL_SECRET_KEY}` },
});
const { data } = await response.json();

const cutoff = Date.now() - 24 * 60 * 60 * 1000;
const release = data.find(
  (candidate) => !candidate.rolled_back && Date.parse(candidate.published_at) <= cutoff,
);
// No match means no release has been public for 24 hours yet: keep your current pin.
```

Run this in your deploy pipeline or a scheduled job, and write `release.script_url` and `release.integrity` into your page template. Each time it runs, also check that the release you have pinned is still listed and is not `rolled_back`.

## Load the pinned release

Replace `https://cdn.usefoil.com/t.js` with the release's `script_url` everywhere your page loads Foil, and give the browser its `integrity` hash in an import map. Put the import map in the page's `<head>`, before any module script runs:

```html theme={"dark"}
<script type="importmap">
  {
    "integrity": {
      "https://cdn.usefoil.com/t.7c1e4b0a9f3d2e6c8b5a4f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c.js": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
    }
  }
</script>
<link
  rel="modulepreload"
  href="https://cdn.usefoil.com/t.7c1e4b0a9f3d2e6c8b5a4f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
  crossorigin
>

<script type="module">
  const foilPromise = import(
    "https://cdn.usefoil.com/t.7c1e4b0a9f3d2e6c8b5a4f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c.js"
  ).then((Foil) =>
    Foil.start({ publishableKey: "pk_live_your_publishable_key" }),
  );
</script>
```

Use the same address in the import map, the `modulepreload` link and the `import()` call. The rest of your integration does not change.

If your Content Security Policy does not allow inline scripts, the browser blocks the import map, and the release loads without the integrity check. Allow it in one of two ways:

* Give the import map the same nonce as your other inline scripts: `<script type="importmap" nonce="your-nonce">`. This keeps working when you move to a new release.
* Add the import map's hash to `script-src`, such as `'sha256-…'`. The hash covers the import map's exact text, so it changes with each release you pin, and you must update the policy each time.

A browser that supports integrity in import maps refuses to run the file if its bytes differ from the hash, so the import fails and Foil does not start. A browser without that support loads the file without the check.

If you call `verifyHuman()`, the pinned release loads one more file from `cdn.usefoil.com` the first time you call it. That file is named by its own SHA-256 hash, and the import map's `integrity` entry does not cover it.

## Pin through a first-party integration

A first-party integration serves every release the API lists at your integration URL, with the same bytes as `cdn.usefoil.com` and the same integrity hash. To pin a release on pages that use the integration, build its address from your integration URL and the release's `id`, `<integration URL>/t.<id>.js`, and use it with the release's `integrity` hash. For the integration URL `https://www.example.com/foil`:

```html theme={"dark"}
<script type="importmap">
  {
    "integrity": {
      "https://www.example.com/foil/t.7c1e4b0a9f3d2e6c8b5a4f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c.js": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
    }
  }
</script>
<link
  rel="modulepreload"
  href="https://www.example.com/foil/t.7c1e4b0a9f3d2e6c8b5a4f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
  crossorigin
>

<script type="module">
  const foilPromise = import(
    "https://www.example.com/foil/t.7c1e4b0a9f3d2e6c8b5a4f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c.js"
  ).then((Foil) =>
    Foil.start({ publishableKey: "pk_live_your_publishable_key" }),
  );
</script>
```

The SDK sends its collection requests through the integration URL it was loaded from, so you don't need to set `endpoint`, and the page loads the SDK without contacting `cdn.usefoil.com`. The `script-src` source you already allow for the integration covers the pinned release's file. The import map is still an inline script, so allow it as described in [Load the pinned release](#load-the-pinned-release).

The integration's own `t.js` keeps following the current release, and **Redeploy** and **Roll back** in the integration's settings change only `t.js`. A pinned page keeps its release through both. Once the API stops listing a release, the integration answers `401` for its address and Foil does not start on the page, so keep your pin current as described below.

## Keep your pin current

* Move to a newer release before your pinned release's `accepted_until`. After that time Foil refuses new sessions from the release with `426 transport.upgrade_required`, and Foil does not start on your pages.
* Move off a release that becomes `rolled_back`. Foil rolls back a release when it has a problem.
* Move at least weekly. A pinned page does not receive Foil's detection updates until you move it to a release that has them.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `401` | `auth.missing_api_key`, `auth.invalid_api_key` | The `Authorization` header is missing, or the key is not valid. |
| `403` | `auth.secret_key_required` | The request used a publishable key. Use a secret key. |
| `403` | `auth.insufficient_scope` | The key does not have the `sdk_releases:read` scope. |
| `500` | `internal.unavailable` | Foil could not read the list. Retry with backoff. |

Every error response includes a `request_id`. Include it when you contact Foil support. See [API errors](https://usefoil.com/docs/api-reference/errors.md).


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