HMAC identity verification

HMAC Identity Verification ensures every user tracked by the platform comes from an authenticated, trusted source. When enabled, the system enforces HMAC validation on all identify calls, blocking tracking of spoofed or unidentified users.

When to use it

• To guarantee trust in user data across analytics and feature management.
• To prevent spoofing, where someone impersonates a user by sending fake events.
• To comply with security and privacy policies for verified user tracking.

How it works

1. An admin generates a secret key in the Identity Verification settings.
2. Developers use the secret to generate an HMAC-SHA256 hash of the user ID (usually userId or email), server-side.
3. The client SDK sends both the userId and the userHash with each identify call.
4. The platform validates the hash against the secret:
   • If valid, the user is tracked.
   • If invalid or missing, the user is rejected and not tracked.

sequenceDiagram
  participant A as Admin
  participant B as Your Backend
  participant C as Client SDK
  participant F as Foldspace
  A->>B: Share secret key (from Settings)
  Note over B: Secret stays server-side
  B->>B: HMAC-SHA256(userId, secret)
  B->>C: userId + userHash
  C->>F: identify(userId, userHash)
  F->>F: Recompute HMAC & compare
  alt Hash matches
      F-->>C: User tracked ✓
  else Hash invalid or missing
      F-->>C: User rejected ✗
  end

Enable Identity Verification

1. Go to Settings → Identity Verification.
2. Click Generate to create a new secret.
3. Copy the secret and store it securely (for example, in a key vault).
4. Share the secret with your development team to implement hashing.
5. Toggle Enforce Identity Verification to ON.
6. Save your changes.

Caution

Once enabled, all identify calls must include a valid HMAC hash. Unverified users will no longer be tracked.

Parameters

Field	Description
userId	Unique identifier of the user (e.g., UUID, email, database ID).
userHash	HMAC-SHA256 hash of userId, signed with the secret. Must be computed server-side.

Generate the user hash

After enabling HMAC, update your identify calls to include userHash. The userHash is an HMAC-SHA256 hash of the userId, signed with the shared secret from the admin.

Caution

Generate the hash in server-side code only. Never expose the secret key in frontend code.

Node.js

const crypto = require("crypto");

function generateUserHash(secret, userId) {
  return crypto.createHmac("sha256", secret).update(userId).digest("hex");
}

const userId = "user_123";
const secret = process.env.FOLDSPACE_SECRET;
const userHash = generateUserHash(secret, userId);

// Pass to the SDK
foldspaceClient.identify({
  userId,
  userHash
});

Python

import hmac
import hashlib

def generate_user_hash(secret, user_id):
    return hmac.new(
        secret.encode("utf-8"),
        user_id.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

user_id = "user_123"
secret = os.getenv("FOLDSPACE_SECRET")
user_hash = generate_user_hash(secret, user_id)

client.identify({
    "userId": user_id,
    "userHash": user_hash
})

Related

• JWT Authentication: protect agent sessions with signed tokens.
• Authentication: API keys and scopes.