Common errors
getSession() returns null or throws
Cause: The Foil SDK hasn’t finished initializing.
Fix: Ensure Foil.start() has resolved before calling getSession(). If you need the fingerprint to be complete, await waitForFingerprint() first.
Sealed token verification fails
Cause: The publishable key used in the browser and the secret key used on the server belong to different organizations. Fix: Verify both keys are from the same organization. Check the dashboard for your active key pairs.All sessions return inconclusive
Cause: The behavioral phase hasn’t collected enough interaction data.
Fix: Don’t call getSession() immediately on page load. Wait until the user has interacted with the page (clicked, typed, scrolled).
Gate webhook returns 401
Cause: TheX-Foil-Signature header doesn’t match.
Fix: Verify you’re computing the HMAC over ${timestamp}.${rawBody} using both the X-Foil-Timestamp and the raw request bytes (not JSON.stringify(req.body) which may reorder keys).
npx signup says “Service not found”
Cause: The service isn’t registered in the Gate registry, or the registry URL is wrong.
Fix: Run npx signup list to see available services. For development, pass --registry-url http://localhost:3000/gate/registry.
Dashboard login redirects to /login
Cause: The login code was already consumed or expired, orGATE_API_ORIGIN points to the wrong server.
Fix: Login codes are one-time-use and expire in 5 minutes. Ensure your dashboard server’s GATE_API_ORIGIN points to the same API that issued the code.
FAQ
Q: Does Foil add latency to my pages? A: The browser SDK loads asynchronously and doesn’t block rendering. ThegetSession() call adds ~50-200ms depending on how much behavioral data has been collected.
Q: What happens if the Foil CDN is down?
A: Your application continues to work. The SDK fails gracefully — getSession() returns null, and you should have a fallback policy (e.g., allow the request but flag it for review).
Q: Can I use Foil with a Content Security Policy?
A: Yes. Add cdn.usefoil.com to your script-src directive and api.usefoil.com to your connect-src directive.
Q: How long are sessions stored?
A: Sessions are available via the API for 90 days. Fingerprints are stored for 1 year.