Get Token Flow

Use this flow when you want your backend to control the SSO handshake directly — calling Business Health yourself to obtain a token (and, optionally, a ready-made redirect URL) before the page loads.

How It Works

sequenceDiagram
    participant BE as Your Backend
    participant BH as Business Health
    participant Page as Widget / Dashboard (browser)

    Note over BE: Assemble SSO Payload,<br/>compute HMAC-SHA-256 signature
    BE->>BH: POST /api/v2/sso/dashboard-login (or .../get-token)<br/>{ payload, signature }
    Note over BH: Verify signature,<br/>create/update user & company,<br/>generate JWT
    BH-->>BE: Redirect URL with JWT (dashboard-login)<br/>or just the JWT (get-token)
    BE->>Page: iframe src=redirectUrl (Dashboard)<br/>or token property (widgets)
    Page->>BH: Widget/Dashboard requests, using the JWT

1. Build SSO Payload

Assemble the SSO Payload on your backend — a JSON object describing the user and their company: name, email, a unique identifier from your platform, and (optionally) additional user and company details. This is the same payload schema used by Component Auth — see SSO Payload for the full schema and what's required.

2. Calculate Signature

Minify the payload JSON (no extra whitespace or escape characters), then compute its HMAC-SHA-256 hash, hex-encoded, using the private key configured for your tenant in the SignedLoginPrivateKey system setting.

{"name":"John Doe","email":"[email protected]","externalId":"123456","isActive":true,"accountData":[{"name":"Acme Corporation","externalId":"67890"}]}

3. Request JWT

Call one of two endpoints, sending payload and signature in the request body:

• SSO Dashboard Login (POST /api/v2/sso/dashboard-login) — returns a redirect URL that already includes the JWT, for embedding the Dashboard.
• SSO Get Token (POST /api/v2/sso/get-token) — returns just the JWT for integrating individual widgets.

Full parameters, request/response bodies, status codes, and an interactive "Try it" console are in the API Reference.

4. Business Health Auth

Business Health verifies the signature, then creates or updates the user and company from the payload — matching against existing records using externalId and/or email — and generates a JWT, returned in response to your request. See How Business Health Matches Users & Companies in Widget & Dashboard Integration for exactly how that matching, creation, and linking works.

5. Use the Result

From SSO Dashboard Login, embed the returned URL directly:

<iframe src="{redirectUrl}"></iframe>

From SSO Get Token — or by extracting the token query parameter out of the Dashboard Login redirect URL — pass the JWT to widgets via their token property:

<{tag-name}
  class="widget-container"
  api="{baseUrl}"
  token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
></{tag-name}>

The same JWT is used by both individual widgets and the Dashboard to communicate with Business Health. See Embedding Widgets for the full walkthrough of adding the widget script and tag to your page.

Token Lifecycle

• Storage: the JWT isn't persisted by the widget — it's kept in memory only, for the lifetime of the current page load. It's never written to localStorage, sessionStorage, or a cookie. This is different from Component Auth, which does persist its token.
• On reload: because nothing is persisted, a full page reload (or a new tab) starts over — your backend needs to call Get Token again and supply a fresh token via the token property, matching the recommended pattern of calling Get Token before each page load, rather than being something to work around.
• Revocation: since the token isn't persisted in the browser, there's typically nothing to revoke — it stops being usable the moment the page is gone, and your backend simply mints a fresh one next time regardless of whatever happened to the old one. If you do want to end a Business Health session explicitly before its natural expiry — for example, tying it to your own platform's logout — call GET /api/AuthService/Logout.
• Refresh: you don't normally need to worry about token expiration here — its lifetime is typically configured to comfortably outlast a normal page session, and your backend re-mints a fresh one on every page load anyway. If you want full control over this, decode the token and check its exp claim yourself, and re-call Get Token ahead of time if you need to extend a long-running page without a reload.

Business Health Settings

Before this flow works, your Business Health teannt needs to be configured with the following system setting: