Component Auth Flow

Use Component Auth when you're embedding individual widgets and would rather not build a separate server-to-server call to Business Health before the page loads. Instead, you tell the widget how to identify the current user through its auth property, and Business Health takes care of the rest — including calling you back to verify the user and fetch their details.

How It Works

sequenceDiagram
    participant W as Widget (browser)
    participant BH as Business Health
    participant UP as Your SSO Endpoint

    Note over W: Page loads with the widget's<br/>auth property set
    W->>BH: GET /api/AuthService/GetToken?authProps1=...&authPropsN=...
    BH->>UP: GET {your-sso-endpoint}?authProps1=...&authPropsN=...
    alt Verification succeeds
        UP-->>BH: 200 OK — user & company JSON (SSO Payload)
        Note over BH: Create/update user & company,<br/>generate JWT
        BH-->>W: JWT
        Note over W: JWT stored in browser,<br/>used by all widgets on the page
    else Verification fails
        UP-->>BH: 401 Unauthorized
        BH-->>W: invalidtoken event
    end

1. auth Property in Widget

Your page loads the widget with an auth property.

The auth property is a JSON object containing whatever parameters you use to identify the current user — a session ID, an internal auth token, and so on. Business Health passes these through unchanged; their structure and content are entirely up to you.

<{tag-name}
  class="widget-container"
  api="{baseUrl}"
  auth='{"authProps1":"...","authPropsN":"..."}'
></{tag-name}>

2. Widget Token Request

The widget requests a token from Business Health, forwarding the auth object unchanged:

GET {baseUrl}/api/AuthService/GetToken?authProps1=...&authPropsN=...

This call is made automatically by the widget itself — you don't write or trigger it yourself. (If you're inspecting network traffic while testing your integration, this is the request you'll see fire when the widget loads.) When multiple widgets share a page, only the first one to load makes this call; the others wait for the resulting token.

3. SSO Request

Business Health calls your SSO endpoint to verify the user and retrieve their details, forwarding the same parameters as a query string:

GET {your-sso-endpoint}?authProps1=...&authPropsN=...

You register {your-sso-endpoint} once per tenant, as the ClientDataServiceUrl system setting. If your endpoint sits behind a proxy, Business Health also needs the proxy details, configured in the ClientDataServiceProxyUrl system setting as user:password@http://proxy-ip-address:port.

4. SSO Endpoint Verification

Your endpoint verifies the parameters and responds with 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 SSO Payload schema used by Get Token — see SSO Payload for the full schema and what's required. If verification fails, respond with 401 Unauthorized.

5. Business Health Auth

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

6. Business Health JWT

The JWT is returned to the widget, as the response to its original request in step 2, and stored in the browser. All widgets on the page use it from then on to communicate with Business Health.

Token Lifecycle

• Storage: the JWT is stored in the browser's localStorage, alongside a few related values (the decoded user ID, an SSO flag, and a hash of the auth parameters used to fetch it) — shared by every widget on the page. This is different from Get Token, which doesn't persist its token at all.
• On reload: because the token persists, a reload doesn't necessarily mean a new network round-trip — the widget checks the stored token's expiry first, and only repeats this flow (calling Business Health, which calls your endpoint again) if it's actually missing or expired.
• Revocation: the same GET /api/AuthService/Logout endpoint ends the underlying Business Health session. Because the token is persisted here, though, a stored-but-unexpired token will keep working against Business Health's API independent of your own platform's session state, unless you explicitly revoke it (or it naturally expires) — worth keeping in mind for shared or kiosk-style devices.
• Refresh: this is the one flow where expiry is handled automatically. The widget proactively decodes the token and checks its expiry, re-running this flow ahead of time if needed, and also automatically retries a request that comes back 401 by re-running the flow and resending it — invisibly to the end user in the common case.

Business Health Settings

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