SSO (Single Sign-On)

​

Overview

• Chat history persistence across sessions
• User memory (the agent remembers preferences)
• Skip login gates
• Subscriber tracking and analytics

​

How It Works

1. You generate an SSO secret in your agent dashboard
2. Your backend creates a signed JWT containing the user’s identity
3. The widget passes the JWT to the agent page
4. BoostGPT verifies the signature and auto-creates or links a subscriber

​

Setup

​

1. Generate an SSO Secret

1. Go to your agent’s Deploy page
2. Find the SSO Secret section under Chat Widget
3. Click Generate
4. Copy the secret — it’s only shown once

​

2. Sign a JWT on Your Backend

const jwt = require('jsonwebtoken');

const SSO_SECRET = 'your-64-char-hex-secret';

function createWidgetToken(user) {
  return jwt.sign({
    email: user.email,         // required
    name: user.name,           // optional
    external_id: user.id,      // optional — your user ID for tracking
  }, SSO_SECRET, { expiresIn: '1h' });
}

// In your route handler:
app.get('/widget-token', (req, res) => {
  const token = createWidgetToken(req.user);
  res.json({ token });
});

import jwt
import time

SSO_SECRET = 'your-64-char-hex-secret'

def create_widget_token(user):
    payload = {
        'email': user.email,       # required
        'name': user.name,         # optional
        'external_id': str(user.id),  # optional
        'exp': int(time.time()) + 3600,  # 1 hour
    }
    return jwt.encode(payload, SSO_SECRET, algorithm='HS256')

​

3. Pass the Token to the Widget

<script src="https://embed.boostgpt.co/widget.js"></script>
<script>
  // Fetch the token from your backend
  fetch('/widget-token')
    .then(res => res.json())
    .then(data => {
      boostgpt.init({
        botId: 'YOUR_BOT_UUID',
        userToken: data.token,
      });
    });
</script>

<script
  src="https://embed.boostgpt.co/widget.js"
  data-bot-id="YOUR_BOT_UUID"
  data-user-token="<%= widgetToken %>"
></script>

​

JWT Payload

​

What Happens on Verification

1. BoostGPT verifies the JWT signature against your SSO secret
2. If the user doesn’t exist in BoostGPT, an account is automatically created (pre-verified)
3. A subscriber record is created for your agent’s project
4. Free tier credits are granted if applicable
5. The user is authenticated in the chat — history and memory work immediately

​

Security

• Never expose your SSO secret in browser code — always sign JWTs on your server
• Tokens expire after 1 hour — generate fresh tokens on each page load
• Regenerating the SSO secret invalidates all existing tokens immediately
• Invalid or expired tokens are silently ignored — the user continues as anonymous
• BoostGPT only accepts HS256 algorithm to prevent algorithm-switching attacks