Quickstart

Before you start:

Import t.js from https://cdn.usefoil.com.
Use a publishable key (pk_*) in the browser and a secret key (sk_*) on your backend.
Keep the secret key server-side only.
The browser never receives Foil verdicts, scores, or visitor IDs.

1. Install the server SDK

npm install @abxy/foil-server

pip install foil-server

go get github.com/abxy-labs/foil-server-go

gem install foil-server

composer require abxy/foil-server

2. Load the browser client

Start the client as early as possible on your page. Keep the returned promise for later use.

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

  async function setupFoil() {
    const foil = await foilPromise;
    foil.onError((error) => {
      console.error("Foil error", error.code, error.message);
    });

    // Optional: surface fingerprinting errors before the action
    void foil.waitForFingerprint().catch(console.error);
  }

  setupFoil().catch(console.error);
</script>

3. Get a session at action time

Right before signup, login, checkout, or another sensitive action, request a sealed handoff and send it to your backend. Add this function to the same <script type="module"> block as step 2. Each module script has its own scope, so a separate block can’t read foilPromise.

async function submitSignup(formData) {
  const foil = await foilPromise;
  const { sessionId, sealedToken } = await foil.getSession();

  const response = await fetch("/api/signup", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      ...formData,
      foil: { sessionId, sealedToken },
    }),
  });

  return response.json();
}

4. Verify on your backend

Verify the sealed token with your secret key. This is a local operation - no network call to Foil.

const { safeVerifyFoilToken } = require("@abxy/foil-server");

app.post("/api/signup", async (req, res) => {
  const result = safeVerifyFoilToken(
    req.body.foil.sealedToken,
    process.env.FOIL_SECRET_KEY,
  );

  if (!result.ok || result.data.decision.verdict === "bot") {
    return res.status(403).json({ error: "Blocked" });
  }

  // Proceed with signup
  createAccount(req.body);
  res.json({ success: true });
});

from foil_server import safe_verify_foil_token
import os

@app.post("/api/signup")
def signup(request):
    result = safe_verify_foil_token(
        request.json["foil"]["sealedToken"],
        os.environ["FOIL_SECRET_KEY"],
    )

    if not result.ok or result.data.decision.verdict == "bot":
        return {"error": "Blocked"}, 403

    create_account(request.json)
    return {"success": True}

import foil "github.com/abxy-labs/foil-server-go"

func signupHandler(w http.ResponseWriter, r *http.Request) {
    var body SignupRequest
    json.NewDecoder(r.Body).Decode(&body)

    result := foil.SafeVerifyFoilToken(
        body.Foil.SealedToken,
        os.Getenv("FOIL_SECRET_KEY"),
    )
    if !result.OK || result.Data.Decision.Verdict == "bot" {
        http.Error(w, "Blocked", 403)
        return
    }

    createAccount(body)
    json.NewEncoder(w).Encode(map[string]bool{"success": true})
}

require "foil/server"

post "/api/signup" do
  body = JSON.parse(request.body.read)
  result = Foil::Server::SealedToken.safe_verify_foil_token(
    body.dig("foil", "sealedToken"),
    ENV.fetch("FOIL_SECRET_KEY"),
  )

  if !result[:ok] || result[:data][:decision][:verdict] == "bot"
    halt 403, { error: "Blocked" }.to_json
  end

  create_account(body)
  { success: true }.to_json
end

use Foil\Server\SealedToken;

$body = json_decode(file_get_contents("php://input"), true);
$result = SealedToken::safeVerify(
    $body["foil"]["sealedToken"],
    getenv("FOIL_SECRET_KEY"),
);

if (!$result->ok || $result->data->decision["verdict"] === "bot") {
    http_response_code(403);
    echo json_encode(["error" => "Blocked"]);
    exit;
}

createAccount($body);
echo json_encode(["success" => true]);

# Alternatively, fetch the session from the API instead of verifying locally:
curl https://api.usefoil.com/v1/sessions/sid_... \
  -H "Authorization: Bearer sk_live_..."

Verification confirms that the token is authentic and that your secret key can open it. It doesn’t check the token’s age or whether you have seen the token before. Before you enforce, add a freshness check as described in What verification doesn’t check.

5. Apply policy

Use the verdict to decide what to do:

Verdict	Action
`human`	Allow the request
`inconclusive`	Challenge (CAPTCHA, email verification)
`bot`	Block or rate-limit

Start in report-only mode (log verdicts without blocking) to understand your traffic before enforcing.

What’s next

Browser SDK

Full SDK API reference

Server verification

Advanced verification patterns

Testing

Test your integration with bot traffic

Going to production

Rollout checklist and monitoring

Overview

Get started

Integrate

Use cases

Learn

Resources

1. Install the server SDK

2. Load the browser client

3. Get a session at action time

4. Verify on your backend

5. Apply policy

What’s next

Browser SDK

Server verification

Testing

Going to production

​1. Install the server SDK

​2. Load the browser client

​3. Get a session at action time

​4. Verify on your backend

​5. Apply policy

​What’s next

Browser SDK

Server verification

Testing

Going to production

1. Install the server SDK

2. Load the browser client

3. Get a session at action time

4. Verify on your backend

5. Apply policy

What’s next