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. Add the auth Property to 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 {api}/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 credentials, configured 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.

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.