SDK Authentication

The Embedding SDK uses JWT tokens to authenticate users seamlessly — your users never see a FlowStack login page.

How It Works

1. Your frontend requests a token from your backend
2. Your backend generates a signed JWT using your FlowStack secret key
3. The JWT is passed to the FlowStackEmbed component
4. FlowStack validates the token and authenticates the user

Backend Token Generation

Node.js / TypeScript

import jwt from 'jsonwebtoken';

function generateFlowStackToken(userId: string, email: string): string {
  const payload = {
    sub: userId,
    email: email,
    projectId: 'your-project-id',
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour
  };

  return jwt.sign(payload, process.env.FLOWSTACK_SIGNING_SECRET);
}

// Express endpoint
app.get('/api/flowstack-token', authenticateUser, (req, res) => {
  const token = generateFlowStackToken(req.user.id, req.user.email);
  res.json({ token });
});

Python

import jwt
import time
import os

def generate_flowstack_token(user_id: str, email: str) -> str:
    payload = {
        'sub': user_id,
        'email': email,
        'projectId': 'your-project-id',
        'iat': int(time.time()),
        'exp': int(time.time()) + 3600,  # 1 hour
    }
    return jwt.encode(payload, os.environ['FLOWSTACK_SIGNING_SECRET'], algorithm='HS256')

JWT Payload Fields

Field	Type	Required	Description
sub	string	Yes	Unique user ID in your system
email	string	Yes	User's email address
projectId	string	Yes	FlowStack project ID
iat	number	Yes	Issued at (Unix timestamp)
exp	number	Yes	Expiration (Unix timestamp, max 24h)
name	string	No	User's display name
role	string	No	'admin', 'editor', or 'viewer' (default: 'editor')

Signing Secret

Find your signing secret in the FlowStack dashboard:

1. Go to Settings → API Keys
2. Copy the Embedding Secret (starts with fs_embed_)
3. Store it as an environment variable on your backend

caution

Never expose the signing secret in client-side code. Only generate tokens on your backend.

Token Refresh

Tokens expire after the duration specified in the exp field. Implement automatic refresh:

function useFlowStackToken() {
  const [token, setToken] = useState<string | null>(null);

  const refreshToken = useCallback(async () => {
    const res = await fetch('/api/flowstack-token');
    const data = await res.json();
    setToken(data.token);
  }, []);

  useEffect(() => {
    refreshToken();
    const interval = setInterval(refreshToken, 50 * 60 * 1000); // Refresh every 50 min
    return () => clearInterval(interval);
  }, [refreshToken]);

  return token;
}

User Provisioning

When a new user generates a token for the first time, FlowStack automatically provisions their account. No manual user creation is needed — the JWT sub field is used as the unique identifier.