Widget Sessions
2 min read
How the embedded calculator authenticates using JWT sessions.
Overview
When the calculator widget loads on a website, it creates a session by activating the license key and receiving a short-lived JWT. This JWT authorizes the widget to run calculations and (optionally) capture leads for the associated tenant.
Session Flow
1
Widget loads
The script tag loads on the page and reads the data-key attribute (license key). The optional data-app attribute selects which calculator to load.
2
Activation request
The widget activates the license key to create an embed session token:
POST /api/license/activate3
JWT issued
The platform returns a short-lived JWT (the "embed JWT") with claims:
json
{
"sub": "site_xxxx",
"tid": "tenant_xxxx",
"dom": ["www.yourfirm.com"],
"plan": "pro",
"scopes": ["calc", "lead", "pdf"],
"exp": 1700003600
}4
Widget operates
The widget uses this JWT for all subsequent API calls (calculations, lead capture, PDF generation) until it expires.
JWT Claims
| Claim | Description |
|---|---|
sub |
Site identifier |
tid |
Tenant ID |
dom |
Allowed domains array |
plan |
Subscription plan (free/pro) |
scopes |
Permitted actions |
exp |
Expiration timestamp |
Security
- Embed JWTs are short-lived (1 hour) and auto-refresh
- Domain validation is enforced — the widget only works on allowed domains
- The JWT is scoped to widget operations only and cannot access portal admin functions
Was this page helpful?