Only your app can say who someone is.

Why it matters

Without verification, anyone on your site can open the console and call HalWidget.identify({ email: "ceo@yourcustomer.com" }) — and suddenly your team sees a competitor's data in the inbox rail, or worse, you act on a forged identity. Verification makes identity a server-side assertion, not a browser claim.

How it works

Each project has an identity secret (Settings → Security). Your server computes HMAC-SHA256(secret, user_id) and passes the hash alongside the identify call. HAL recomputes the hash; a mismatch is rejected. The secret never reaches the browser.

visitor                          your server            HAL
   │  login                            │                   │
   ├──────────────────────────────────►│                   │
   │                                   │ hash = HMAC-SHA256│
   │   identity: { user_id, hash }     │   (secret, id)    │
   ├──────────────────────────────────►│                   │
   │                                   ├──────────────────►│
   │                                   │      verified ✓   │

Get your secret

Settings → Security → Identity verification → reveal secret. Rotate it any time; old hashes stop working immediately after rotation.

Generate the hash

// Node.js
import { createHmac } from "crypto";
const hash = createHmac("sha256", secret).update(userId).digest("hex");

# Python
import hmac, hashlib
hash = hmac.new(secret.encode(), user_id.encode(), hashlib.sha256).hexdigest()

# Ruby
hash = OpenSSL::HMAC.hexdigest("sha256", secret, user_id)

// PHP
$hash = hash_hmac("sha256", $userId, $secret);

Pass it to the widget

HalWidget.identify({
  user_id: "usr_123",
  email: "mia@novaleaf.com",
  user_hash: "<hmac-hash>"
});

For server-side identify, include user_hash in the JSON body of POST /api/widget/identify.

Enforce it

Verification is opt-in per project. Once your embeds send signatures, flip on require verified identity in Settings → Security. From then on, unsigned identify calls are ignored — visitors stay anonymous instead of claiming an identity they can't prove.

Key handling rules

See security notes for secret storage, rotation, and what to do if a secret leaks.