Skip to main content

​
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: 
{
  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: 
// 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: 
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.