Server verification

Foil is designed around backend verification. The browser sends your backend a fresh { sessionId, sealedToken } handoff, and your backend decides whether to allow, challenge, throttle, or block the action.

Recommended flow

Start Foil early

Initialize the browser client on page load so collection begins before the user reaches the protected action.

Request a fresh session handoff

Right before signup, checkout, login, or another sensitive action, call foil.getSession().

Submit the handoff with the business action

Send { sessionId, sealedToken } to your backend alongside your normal payload.

Verify on the server

Use the SDK to verify the sealed token locally with your secret key.

Apply policy

Allow, challenge, rate-limit, or block based on the verdict.

Browser handoff

<script type="module">
  const { sessionId, sealedToken } = await foil.getSession();

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

Verify the sealed token

The primary verification path. Local, fast, no network call to Foil. The iOS and Android SDKs return the same { sessionId, sealedToken } handoff, and you verify a native token the same way as a browser token.

The method is named safeVerifyFoilToken (and snake/Pascal variants) in every SDK except PHP, where it is SealedToken::safeVerify.

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

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

  if (!result.ok) {
    return res.status(500).json({ error: "Verification failed" });
  }

  console.log(result.data.decision.verdict);    // "human", "bot", or "inconclusive"
  console.log(result.data.decision.risk_score); // 0–100
  console.log(result.data.session_id);

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

  // Proceed with the action
});

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:
        return {"error": "Verification failed"}, 500

    print(result.data.decision.verdict)    # "human", "bot", or "inconclusive"
    print(result.data.decision.risk_score) # 0 – 100

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

    # Proceed with the action

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

func signupHandler(w http.ResponseWriter, r *http.Request) {
    var body struct {
        Foil struct {
            SealedToken string `json:"sealedToken"`
        } `json:"foil"`
    }
    json.NewDecoder(r.Body).Decode(&body)

    result := foil.SafeVerifyFoilToken(
        body.Foil.SealedToken,
        os.Getenv("FOIL_SECRET_KEY"),
    )
    if !result.OK {
        http.Error(w, "Verification failed", 500)
        return
    }

    if result.Data.Decision.Verdict == "bot" {
        http.Error(w, "Blocked", 403)
        return
    }

    // Proceed with the action
}

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"),
  )

  halt 500, { error: "Verification failed" }.to_json unless result[:ok]

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

  # Proceed with the action
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) {
    http_response_code(500);
    echo json_encode(["error" => "Verification failed"]);
    exit;
}

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

// Proceed with the action

# Use the SDK for local verification. For API-based readback, see below.

What verification doesn’t check

Verification confirms that the token is authentic and that your secret key can open it. The server SDKs decrypt the token and return its contents. They don’t check how old the token is, and they don’t remember which tokens they have seen. Two things follow from that:

A token has no expiry. Every getSession() call produces a new token, and the token’s decision.evaluated_at records when Foil produced it. A token that someone captured from a real browser still verifies later, so reject tokens whose evaluated_at is more than a few minutes old.
A token can be submitted more than once. Verification is stateless. To reject repeats, record the decision.event_id of each token you accept, which is unique to each token, or the session_id if you allow one action per session.

Also use the session_id from the verified token, not the sessionId that the browser sent. Nothing in the request ties the browser’s sessionId field to the token, so a caller can send a valid token next to a different session ID. The following example treats a token that fails verification or is more than five minutes old as missing:

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

const MAX_TOKEN_AGE_MS = 5 * 60 * 1000;

function verifyFoil(handoff) {
  if (!handoff?.sealedToken) return null;

  const result = safeVerifyFoilToken(
    handoff.sealedToken,
    process.env.FOIL_SECRET_KEY,
  );
  if (!result.ok) return null;

  const age = Date.now() - Date.parse(result.data.decision.evaluated_at);
  if (age > MAX_TOKEN_AGE_MS) return null;

  return result.data;
}

Decide in your policy what a missing token means. See Verify the token on your server in the checkout guide for a complete example in every server SDK language.

Alternative: session readback

If you prefer to fetch the full session from the API (useful for async or audit workflows):

const resp = await fetch(
  `https://api.usefoil.com/v1/sessions/${sessionId}`,
  { headers: { Authorization: `Bearer ${process.env.FOIL_SECRET_KEY}` } }
);
const session = await resp.json();

console.log(session.data.decision.automation_status); // "human", "automated", or "uncertain"
console.log(session.data.decision.risk_score);        // 0 – 100

import requests

resp = requests.get(
    f"https://api.usefoil.com/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {os.environ['FOIL_SECRET_KEY']}"},
)
session = resp.json()

print(session["data"]["decision"]["automation_status"])
print(session["data"]["decision"]["risk_score"])

curl https://api.usefoil.com/v1/sessions/sid_... \
  -H "Authorization: Bearer sk_live_..."

Key fields in the session readback response:

Field	Description
`decision.automation_status`	`human`, `automated`, or `uncertain`
`decision.risk_score`	integer `0` (human) to `100` (bot)
`decision.evaluation_phase`	`snapshot`, `behavioral`, or `null`
`decision.decision_status`	`preliminary` or `final`
`client_user_id`	Your own end-user ID, if you attached one
`highlights`	Top signals that influenced the decision
`attribution`	Labels for what is behind the session, such as the actor, tool, and provider
`visitor_fingerprint`	Persistent device identifier

Attach your user ID

If the Foil session starts before the user exists in your database, attach your user ID after signup succeeds from your backend. Pass the session_id from the verified token.

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

const client = new Foil({ secretKey: process.env.FOIL_SECRET_KEY });

await client.sessions.attachClientUser(sessionId, user.id);
// Later, if needed:
await client.sessions.clearClientUser(sessionId);

from foil_server import Foil

client = Foil(secret_key=os.environ["FOIL_SECRET_KEY"])

client.sessions.attach_client_user(session_id, user.id)
# Later, if needed:
client.sessions.clear_client_user(session_id)

client, err := foil.NewClient(foil.WithSecretKey(os.Getenv("FOIL_SECRET_KEY")))
if err != nil {
    log.Fatal(err)
}

_, err = client.Sessions.AttachClientUser(ctx, sessionID, user.ID)
_, err = client.Sessions.ClearClientUser(ctx, sessionID)

client = Foil::Server::Client.new(secret_key: ENV.fetch("FOIL_SECRET_KEY"))

client.sessions.attach_client_user(session_id, user.id)
client.sessions.clear_client_user(session_id)

use Foil\Server\Client;

$client = new Client(secretKey: getenv("FOIL_SECRET_KEY"));

$client->sessions()->attachClientUser($sessionId, $user->id);
$client->sessions()->clearClientUser($sessionId);

curl -X PATCH https://api.usefoil.com/v1/sessions/sid_... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"client_user_id":"user_123"}'

Policy patterns

Pattern	When to use	Example
Report only	First week of integration	Log verdicts, don’t block anyone
Soft challenge	`inconclusive` on sensitive endpoints	Show CAPTCHA or require email verification
Hard block	`bot` on signup, checkout, scraping	Return 403 immediately
Rate control	Repeated fingerprints	Slow down instead of blocking

Start in report-only mode. Once you understand your traffic’s verdict distribution, gradually enable enforcement.

What’s next

Testing your integration - simulate bot traffic and debug
Going to production - rollout checklist
Verdicts & scoring - understand what scores mean
Sessions API - full API reference

Overview

Get started

Integrate

Use cases

Learn

Resources

Server verification

Recommended flow

Browser handoff

Verify the sealed token

What verification doesn’t check

Alternative: session readback

Attach your user ID

Policy patterns

What’s next

​Recommended flow

​Browser handoff

​Verify the sealed token

​What verification doesn’t check

​Alternative: session readback

​Attach your user ID

​Policy patterns

​What’s next

Recommended flow

Browser handoff

Verify the sealed token

What verification doesn’t check

Alternative: session readback

Attach your user ID

Policy patterns

What’s next