Guides
Identity verification
Sign each user ID on your server so nobody can read or fake another user's messages.
Why it matters#
Your public key is in your page source. Without identity verification, anyone who copies it can read another user's messages, use up their frequency caps and fake their clicks.
With it, your server signs each user ID and Tug refuses /decisions and /feedbackcalls whose signature doesn't match. Calls with a server API key skip the check.
Set it up#
On the project page, under Identity verification and key rotation, click Create secret. The secret starts with fis_ and is shown once: store it on your server, for example as TUG_IDENTITY_SECRET.
Compute userHash#
userHash is the lowercase hex HMAC-SHA256 of the user ID, keyed with the secret. Compute it on your server and hand it to the page along with the user ID.
server.ts · TypeScript
import { createHmac } from "node:crypto";
// On your server, for the signed-in user
const userHash = createHmac("sha256", process.env.TUG_IDENTITY_SECRET)
.update(user.id)
.digest("hex");Send it with each call#
// Render user.id and userHash into the page, then:
window.tugConfig = { publicKey: "phk_live_…", userHash };
// Or after login, with identify:
tug.identify(user.id, { plan: "pro" }, { userHash });Then check that responses carry X-Tug-Identity: verified. The other values are unverified (no hash sent), invalid and server_key.
Require it#
When every page sends a hash, click Require identity verification. From then on:
- a missing hash is a
401missing_user_hash; - a wrong one is a
401invalid_user_hash.
Rotate the secret#
- Rotate secretissues a new one. The old secret keeps working for 24 hours, so pages already loaded don't break.
- Put the new secret on your servers within those 24 hours.
- Optional: Revoke old secret now ends the grace period early, for example after a leak.