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 reponse to your request.

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.