How to embed DashboardFox content within your application

You can show DashboardFox dashboards and reports inside your own application, and sign users into DashboardFox without a second login screen. Both use the same mechanism: your application signs in through the API to get a session token, then places that token in a URL.

This article covers the flow end to end: choosing the right account to sign in with, getting a token, embedding a dashboard or report, passing report prompts, and sending users straight into the DashboardFox interface.

Before you embed: decide who signs in

Your application will call the login API with a username and password it stores. Three things follow from that, and they are the cause of most embedding problems:

1. Use accounts your application owns. Create DashboardFox users specifically for embedding and mark each one as a service account in the user editor (Additional Options → Service account (API integration)). A service account is never asked for a two-factor code or a forced password change, so turning on two-factor authentication or password policies later cannot break your integration. See Service Accounts for Integrations and Embedding.

2. One sign-in model per user. An account that your application signs in on someone's behalf should not also be an account that person manages themselves. Once they enroll in two-factor authentication or change their own password, your application can no longer sign in as them. Either users manage their own credentials and sign in to DashboardFox directly, or your application owns the credentials and those accounts stay service accounts with two-factor off. Mixing the two on one account is what breaks embeds.

3. One session per user. DashboardFox keeps a single session per account. Each successful login issues a new token and ends that account's previous session. If several people share one embedding account, each page load signs the previous viewer out. Give each end user — or at least each tenant — their own DashboardFox account, and cache each account's token on your server rather than logging in on every page view.

If your end users must have two-factor authentication for compliance, sign them in through single sign-on or the External authentication method instead of storing their passwords; then their identity provider enforces the second factor and DashboardFox does not prompt.

Public content. For dashboards or reports anyone may see without signing in, turn on Anonymous / Public view when saving the item and use its public link. No token or account is needed.

1. Get a session token

Call the login endpoint from your server, never from the browser, so the password is never exposed:

POST https://your-dashboardfox-server.com/api/Login/DoLogin
Content-Type: application/json
 
{
  "bolForceLogin": true,
  "isGuest": false,
  "UserId": "svc-embed-tenant-a",
  "UserPassword": "YOUR_PASSWORD"
}

A successful response has ErrorCode: 0 and the token in LoginSession.SessionToken:

{
  "ErrorCode": 0,
  "ErrorMessage": "",
  "LoginSession": {
    "SessionToken": "LVPACMJFBMZKUHRIXMQSTUZUY",
    "isGuestSession": false,
    "SessionExpir": "2026-10-22T20:14:03.4458383+00:00"
  },
  "LoginUser": { "LoginName": "svc-embed-tenant-a", "..." : "..." }
}

Wrong credentials, a disabled account, or an account temporarily locked after repeated wrong passwords all return ErrorCode: 101.

If the response includes requiresTwoFactor: true or requiresTwoFactorEnrollment: true, the account has a two-factor step to complete and the token is not usable yet — every other call with it is refused. Likewise LoginUser.bforcepasschange: true means a new password must be set first. Both mean the account is not a service account; fix that in the user editor rather than retrying.

Token lifetime. The token expires at SessionExpir (20 minutes after the last call by default) and the window moves forward on every request, so an embed someone is using stays alive on its own. For an embed that may sit untouched, call /api/Session/RefreshSession with the token before it expires, and /api/Session/CheckSession to test whether a token is still valid. A token that returns ErrorCode: 101 has expired or been replaced by a newer login; log in again.

2. Embed a dashboard or report

Append the token to an embed URL. t=d is a dashboard, t=r a report, and i= the item's ID:

Dashboard:  https://your-dashboardfox-server.com/embed.html?t=d&i={dashboardId}&s={sessionToken}
Report:     https://your-dashboardfox-server.com/embed.html?t=r&i={reportId}&s={sessionToken}

Place either URL in an <iframe> on your page, or use it as a direct link:

<iframe src="https://your-dashboardfox-server.com/embed.html?t=d&i=123&s=LVPACMJFBMZK..."
        width="100%" height="700" frameborder="0"></iframe>

Paths. On DashboardFox Cloud and Linux installs the page is /embed.html. On a default Windows install it is /dashboardfox/embed.html, and the API is /dashboardfox/api/….

3. Find dashboard and report IDs

Open the dashboard or report in edit mode; the ID is shown at the top right of the edit sidebar. When you enable embedding on an item, DashboardFox also adds an Embed entry to its Library menu with copy-ready links.

4. Pass report prompts

If a report has prompts, you can pre-fill them in the URL with isprompt=true and indexed prmpt* parameters. The Embed Library in DashboardFox builds this link for you — open the report's Embed entry, set the prompt values, and copy the result. A typical link looks like:

https://your-dashboardfox-server.com/embed.html?t=r&i=1739550061&isprompt=true&prmpt0low=11000&prmpt0skipped=false&s={sessionToken}

Each prompt carries a value plus skipped, like and between settings. Put the finished link in an iframe for a report that opens already filtered.

5. Sign users straight into DashboardFox

The same token signs a user into the full DashboardFox interface through sso.html, landing on the view you choose:

Dashboard (default):  https://your-dashboardfox-server.com/sso.html?s={sessionToken}
Library:              https://your-dashboardfox-server.com/sso.html?s={sessionToken}&h=1
Builder:              https://your-dashboardfox-server.com/sso.html?s={sessionToken}&h=2

Use this as the target of a button or redirect in your application. Because the user lands inside the real interface, this is where the "one sign-in model" rule matters most: a person sent through sso.html on an account they also manage themselves will meet the two-factor or new-password screen the first time those features are turned on.

Checklist

  1. A dedicated DashboardFox user per end user or tenant, marked as a service account, with a long random password stored only on your server.

  2. DoLogin called server-side; token cached and reused; ErrorCode: 101 handled by logging in again.

  3. requiresTwoFactor, requiresTwoFactorEnrollment and bforcepasschange treated as "fix the account", not "retry".

  4. Embed URLs built with the item ID and token; RefreshSession for long-lived embeds.

  5. Content access granted to the embedding account through its groups and application roles, with data-security policies applied where tenants must stay separated.

Related