# HMAC identity verification

Enforce HMAC-SHA256 verification on identify calls so only authenticated, trusted users are tracked.

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.

<Mermaid chart={`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**

    ```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**

    ```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](/security/jwt/): protect agent sessions with signed tokens.
- [Authentication](/start/authentication/): API keys and scopes.