Technical

Authentication

Your user already logged in — to you. Making them log in again would be absurd, so the platform vouches: your server mints a short-lived token saying who they are, signed with your app's secret. You never call our API to do it, and we never see your user database.

Minting the token#

js — your server, any JWT library

import { SignJWT } from 'jose';

const token = await new SignJWT({ name: user.displayName })
  .setProtectedHeader({ alg: 'HS256' })
  .setSubject(user.id)          // your id for them — any stable string
  .setIssuedAt()
  .setExpirationTime('5m')      // tokens are per page load, not per person
  .sign(new TextEncoder().encode(process.env.HUDDLES_APP_SECRET));

"Server" is generous. A Cloudflare Worker or a Netlify function is plenty. The token is per page load, not per person: fifteen minutes is the ceiling and five is typical.

Token claims#

Claim
`sub`	Required. Your stable id for the user (≤128 chars). It is what makes them the same person every visit.
`name`	Required. Display name (≤40 chars). Rename them on your side and they rename here.
`exp`	Required, ≤15 minutes out. Tokens are per page load.
`avatar`	Optional: `{ type: 'grad', i: 0–11 }`. Otherwise a face is drawn from their id.

The handshake#

The iframe says hello
The widget draws the bar and mounts /embed/<appId>, which is the app served framable by your registered origins and nobody else's. The app posts huddles:ready.
The widget hands over the token
By postMessage, to our origin only — never a URL. A token in a URL is a token in a log.
The app trades it for a session
POST /api/embed/session verifies the signature and answers with a session whose cookie is Partitioned, SameSite=None, Secure — the trio that works inside somebody else's site now that third-party cookies are dead.
Identity is derived, so it is stable
The Huddles user is hash(appId, sub): the same classmate keeps their avatar, huddles and boards across visits, and we learn nothing about them beyond what you chose to say.

Shape two is walk-ins: no token at all, an identity minted on the fly, where your app allows it.