Widget & Dashboard Integration

UPTIQ Business Health brings business health insights into your own platform in two ways:

• Widgets — individual components (Accounts, Credit Score, Cash Flow Forecast, and others) embedded directly into your pages.
• Business Health Dashboard — the full dashboard experience, embedded as an iframe.

In order to show a specific user's data in Business Health, both approaches require a signed-in session for that user. This section explains how Business Health authenticates your users via Single Sign-On (SSO), so they never have to create or remember a separate Business Health password.

Three Ways to Set Up SSO

All three approaches produce the same result: a Business Health access token (JWT) that widgets and the Dashboard use to communicate with Business Health on the user's behalf, and all three create or update the user's Business Health account from the same underlying data — see SSO Payload for that shared schema.

How Business Health Matches Users & Companies

Once any of the three flows above delivers a payload (directly, or via SAML's CUSTOMER/COMPANY claims), Business Health resolves it the same way:

• Matching the user: Business Health looks for an existing user whose Business Health login matches the payload's externalId (or, if externalId was omitted, matches its email instead). If none is found, a new user is created from the payload's fields — name/firstName/lastName, email, externalId, isActive, and language.

• Matching each company (every entry in accountData): if accountData.externalId is provided, Business Health looks for a company with that externalId anywhere in Business Health, regardless of which user(s) it's already linked to. If accountData.externalId is omitted, Business Health instead looks for a company already linked to this user that matches an identifier you provided (accountData.identifier, e.g. an SSN or EIN). Either way, if a match is found, that company is updated, not duplicated; if none is found, a new company is created from the accountData fields.

  📘

  A Company Can End Up Shared Across Users

  If the same accountData.externalId shows up in more than one user's login (for example, several employees of the same business), each login links to the same Business Health company record instead of creating a separate copy per user.

• One user can have multiple companies, and one company can have multiple users — linked in a genuine many-to-many relationship, built up incrementally as logins happen over time.

• accountData.isActiveCompany marks which company (if a payload describes more than one) should be treated as the user's current/selected one; only the first entry flagged true is honored. This is re-evaluated on every login — a company not flagged active in a given payload has its active status explicitly cleared for that login, not just left alone.

• A company's externalId is set once, when it's first created, and isn't changed by later logins even if a later payload's value for that company differs. Its other fields (name, email, phone, address) are kept in sync on every login.

How It Fits Together

flowchart TD
    A[User logs in to<br/>User Platform] --> B{SSO handshake}
    B -->|Get Token| D[Backend-initiated —<br/>see Get Token Flow]
    B -->|Component Auth| C[Widget-initiated —<br/>see Component Auth Flow]
    B -->|SAML| S[IdP-federated —<br/>see SAML Flow]
    D --> E[Business Health creates/updates<br/>User & Company, issues JWT]
    C --> E
    S --> E
    E --> F[Widgets and/or Dashboard render,<br/>using the JWT]

    F -.optional.-> G[User Platform Data:<br/>Business Health pulls data directly<br/>from the User Platform]
    F -.optional.-> H[Third-Party App Data:<br/>user connects an external app<br/>via the App Connector widget]

    style G stroke-dasharray: 5 5
    style H stroke-dasharray: 5 5

Provisioning Without SSO

All three SSO approaches above create a company as part of a user's login. Business Health also supports provisioning your platform's clients ahead of time — independent of whether or when they log in.

One way to do this: create a company directly with the Create company endpoint, using the same externalId you'd otherwise send in the SSO Payload's accountData. If that user later logs in via SSO, Business Health matches on externalId and updates the existing company instead of creating a duplicate.