> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teamai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity Verification

> Securely verify user identities when interacting with TeamAI chatbots embedded on your website

## Overview

Our identity verification system allows you to:

* Securely pass user information to chatbots
* Connect interactions to actual user accounts
* Track user history and interactions

## How It Works

1. Generate a secret key for your workspace in the TeamAI dashboard
2. On your server, create an HMAC-SHA256 hash of a user's ID using this secret
3. Send the user ID and hash to your frontend
4. Use the TeamAI SDK's `identify` method to verify the user

<Warning>
  Never expose your secret key in client-side code. Always generate the hash on your server.
</Warning>

## Obtaining the User Hash

The secret key is generated in the TeamAI dashboard under Settings > Identity Verification. Use this key to generate a hash on your server:

```javascript theme={null}
// Node.js example
const crypto = require("crypto");

const secret = "your_workspace_secret"; // Your verification secret key
const userId = "user_123"; // A unique identifier for your user

const hash = crypto.createHmac("sha256", secret).update(userId).digest("hex");
```

## Identity Method

Use the `identify` method to verify user identity:

```javascript theme={null}
const chatbotInstance = tai.getInstance("YOUR_ASSISTANT_ID");

chatbotInstance.identify({
  user_id: "user-123",
  user_hash: "computed-hash-from-server",
  user_metadata: { 
    name: "John Doe",
    email: "john@example.com",
    company: "Acme Inc"
  }
});
```

### Parameters

| Property       | Type   | Required | Description                                             |
| -------------- | ------ | -------- | ------------------------------------------------------- |
| user\_id       | string | Yes      | Unique identifier for the user                          |
| user\_hash     | string | Yes      | Server-generated HMAC SHA-256 hash of the user\_id      |
| user\_metadata | object | No       | Additional user information (max 1000 characters total) |

The `user_metadata` object can include any user attributes you want to make available to your chatbot, such as name, email, or custom fields.

## Complete Example

This example shows how to implement identity verification in a real application:

```javascript theme={null}
// On your server (Node.js example)
app.get('/api/auth/chatbot-identity', isAuthenticated, (req, res) => {
  const userId = req.user.id;
  const secret = process.env.TEAMAI_VERIFICATION_SECRET;
  
  // Generate the hash using HMAC SHA-256
  const hash = crypto.createHmac("sha256", secret).update(userId).digest("hex");
  
  // Return the data to your frontend
  res.json({
    userId: userId,
    userHash: hash
  });
});

// On your frontend
window.addEventListener("teamAIChatbotReady", async function() {
  const chatbotInstance = tai.getInstance("YOUR_ASSISTANT_ID");

  try {
    // Fetch identity verification data from your server
    const response = await fetch('/api/auth/chatbot-identity');
    const { userId, userHash } = await response.json();
    
    // Verify user identity
    chatbotInstance.identify({
      user_id: userId,
      user_hash: userHash,
      user_metadata: {
        name: userProfile.name,
        email: userProfile.email,
        plan: userProfile.subscription
      }
    });
    
    console.log('User identity verified successfully');
  } catch (error) {
    console.error('Identity verification failed:', error);
  }
});
```

## Security Considerations

* Never expose your verification secret key in client-side code
* Always generate the hash on your server
* Use HTTPS for all communication between your server and client
* The user\_id should be a unique identifier that doesn't change for each user
* Consider using a UUID or database ID rather than personally identifiable information

## Troubleshooting

If identity verification fails:

1. Make sure you're using the correct environment for your test (local vs production)
2. Verify that the user ID in your hash generation matches the one you're passing to `identify()`
3. Check the browser console for any error messages from the SDK
4. Enable debug mode by adding `?teamAIDebug=true` to your URL to see detailed logs