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

# Widget Authentication

> How the widget authenticates users securely.

## Auth flow

The widget uses a dedicated **widget JWT** — separate from your application's auth. Here's how it works:

```
1. SDK collects session context (sessionId, anonymousId, userId, sdkKey, device)
2. SDK sends context to widget iframe via postMessage
3. Widget iframe POSTs to /public/widget/auth
4. API validates the SDK key, creates/finds the user, returns a widget JWT
5. Widget stores the JWT and sends hacktionbase:widget_auth_success back to SDK
```

## Session context

The SDK sends a `WidgetContextPayload` to the widget on every auth handshake:

```typescript theme={null}
{
  sessionId: string;      // Current session ID
  anonymousId: string;    // Persistent anonymous ID (survives sessions)
  userId?: string;        // Set after identify() is called
  accountId?: string;     // Set if user has an account
  userHash?: string;      // HMAC for identity verification
  sdkKey: string;         // Your SDK key
  timestamp: number;      // Current timestamp
  device: DeviceInfo;     // Browser, OS, screen, language, timezone
}
```

## When re-authentication happens

The widget re-authenticates in these cases:

* **Initial load** — when the iframe sends `hacktionbase:ready`
* **First identify** — when an anonymous user is identified (anonymous → known user)
* **Account switch** — when `identify()` is called with a different `account.id`

## Identity verification (optional)

To prevent users from impersonating others, you can enable **HMAC identity verification**. Generate the hash server-side using your SDK secret:

```javascript theme={null}
// Server-side (Node.js)
const crypto = require('crypto');
const userHash = crypto
  .createHmac('sha256', 'YOUR_SDK_SECRET')
  .update(userId)
  .digest('hex');
```

Then pass it to `identify`:

```javascript theme={null}
Hacktionbase.identify({
  id: 'user_123',
  email: 'jane@example.com',
  userHash: 'computed_hmac_hash'
});
```

When `userHash` is provided, the API validates it before accepting the identity.