{ sessionId, sealedToken } handoff, and your backend decides whether to allow, challenge, throttle, or block the action.
Recommended flow
1
Start Foil early
Initialize the browser client on page load so collection begins before the user reaches the protected action.
2
Request a fresh session handoff
Right before signup, checkout, login, or another sensitive action, call
foil.getSession().3
Submit the handoff with the business action
Send
{ sessionId, sealedToken } to your backend alongside your normal payload.4
Verify on the server
Use the SDK to verify the sealed token locally with your secret key.
5
Apply policy
Allow, challenge, rate-limit, or block based on the verdict.
Browser handoff
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.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, they don’t remember which tokens they have seen, and they don’t wait for a final result. Three things follow from that:-
A token has no expiry. Every
getSession()call produces a new token, and the token’sdecision.evaluated_atrecords when Foil produced it. A token that someone captured from a real browser still verifies later, so reject tokens whoseevaluated_atis more than a few minutes old. -
A token can be submitted more than once. Verification is stateless. To reject repeats, record the
decision.event_idof each token you accept, which is unique to each token, or thesession_idif you allow one action per session. -
A token can carry a provisional result. A token minted before the visitor has interacted with the page holds a snapshot-phase result with
decision.is_provisionalset totrue. Foil may finish the session later with a different risk score, and that final result doesn’t come back through the token you already verified. If your policy depends on a fine threshold, treat a provisional token as provisional: callgetSession()again after the visitor has interacted, or read the session’s final result with the Sessions API or a webhook. See Preliminary vs final.
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:
Alternative: session readback
If you prefer to fetch the full session from the API (useful for async or audit workflows):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 thesession_id from the verified token.
client_application_id, either alone or in the same request as client_user_id:
Policy patterns
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