Frontend Setup

There are two ways to deploy dashboard in your front end:

iFrame Embedding
Native React Component Embedding 🔒

iFrame Embedding
Native React Component Embedding 🔒

Please click on the Deploy button in the Hub.

You will need to get the JWT for the current user and the dashboard ID to render the correct dashboard. The JWT is generated by following the steps in Backend Setup. The dashboard ID could be found in the URL when you are viewing the dashboard you want to embed.

Important: Changing the JWT token in the iframe src will cause the browser to reload the entire iframe. This happens automatically when:

The JWT expires and gets refreshed
User switches tenants/organizations
Tenant permissions are updated

Plan your token refresh strategy to minimize user disruption.

Below is an example of deploying component with JWT using Clerk middleware:

"use client";
import React from "react";
import { useUser } from "@clerk/nextjs";

const Analytics: React.FC = () => {
  // Get the user information from Clerk and extract the Upsolve token from the metadata
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];

  // Embed the component into your app
  return (
    <>
      {upsolveToken != null && typeof upsolveToken === "string" && (
        <iframe
          id="c5da5cb3-fedb-4656-9170-0cc65c9db29a"
          title="Example Dashboard"
          width="1000"
          height="1000"
          src={`https://hub.upsolve.ai/share/dashboard/c5da5cb3-fedb-4656-9170-0cc65c9db29a?theme=light&jwt=${upsolveToken}`}
        />
      )}
    </>
  );
};

export default Analytics;

Optional: Lock to a specific dashboard version

// Add &version=5 to lock to version 5
src={`https://hub.upsolve.ai/share/dashboard/c5da5cb3-fedb-4656-9170-0cc65c9db29a?theme=light&jwt=${upsolveToken}&version=5`}

Understanding JWT Changes and Iframe Refresh

When the upsolveToken value changes in the code above, React will re-render the component with a new src URL for the iframe. This causes the browser to completely reload the iframe content.

// Example: Token change triggers iframe reload
const Analytics: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];

  // When upsolveToken changes (e.g., from token refresh or tenant switch),
  // the iframe src changes, triggering a full browser reload of the iframe

  return (
    <iframe
      src={`https://hub.upsolve.ai/share/dashboard/abc?jwt=${upsolveToken}`}
      // ↑ Changing upsolveToken here causes iframe reload
    />
  );
};

Common scenarios that trigger iframe reload:

Automatic token refresh (every hour)
User switches between tenants/organizations
User logs out and back in
Tenant permissions are updated

To improve user experience during token updates: 1. Cache the previous token until just before expiration 2. Show a loading overlay during refresh 3. Coordinate token updates during natural breaks in user workflow

Database Row-Level Security (RLS) Setup 🔒

For databases with Row-Level Security policies (Postgres, Redshift, or Supabase), you need to include a database auth token (dbAuthToken) in the iFrame src URL. This token identifies the current user and is used by your database’s RLS policies to filter data at the row level.Example updated iFrame URL:

<iframe
  id="c5da5cb3-fedb-4656-9170-0cc65c9db29a"
  title="Example Dashboard"
  width="1000"
  height="1000"
  src="https://hub.upsolve.ai/share/dashboard/c5da5cb3-fedb-4656-9170-0cc65c9db29a?theme=light&jwt=<upsolveToken>&dbAuthToken=<yourDbAuthToken>"
/>

dbAuthToken: The user-specific identifier that your RLS policies use for row-level filtering

For Postgres and Redshift

The dbAuthToken should contain the value that matches your RLS session variable (e.g., tenant ID, user ID, or company code):

const Analytics: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];
  const tenantId = user?.publicMetadata?.["tenantId"]; // Your user's tenant/company identifier

  return (
    <iframe
      src={`https://hub.upsolve.ai/share/dashboard/abc123?jwt=${upsolveToken}&dbAuthToken=${tenantId}`}
    />
  );
};

Learn more about setting up RLS for Postgres and Redshift in the Database Row-Level Security guide.

For Supabase

To retrieve the Supabase session token (dbAuthToken), you can use Supabase’s auth.getSession method:

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  'https://your-supabase-project.supabase.co',
  'public-anon-key'
);

async function getDbAuthToken() {
  const {
    data: { session },
    error,
  } = await supabase.auth.getSession();

  if (error) {
    console.error('Error retrieving session:', error.message);
    return null;
  }

  return session?.access_token;
}

getDbAuthToken().then((dbAuthToken) => {
  console.log('dbAuthToken:', dbAuthToken);
  // Use dbAuthToken in the iframe URL
});

Refer to the Supabase API docs for more details on managing sessions and tokens.

Import Upsolve AI SDK

Ask the Upsolve AI team for “a key to the private NPM library”. Use the key in your .npmrc or .yarnrc file. You can then import the SDK into your application. Use the key as follows:

If you are using `npm` or `yarn v1`

Add your key to your .npmrc. DO NOT COMMIT this file (more details here):

.npmrc

@upsolve-labs:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken={YOUR_UPSOLVE_TOKEN}

If you are using `yarn v2+`

Add your key to your .yarnrc.yml. DO NOT COMMIT this file (more details here):

.yarnrc.yml

nodeLinker: node-modules

# Use the correct yarn path here based on your version
yarnPath: .yarn/releases/yarn-4.1.0.cjs

npmScopes:
  upsolve-labs:
    npmRegistryServer: "https://npm.pkg.github.com/"
    npmAuthToken: "{YOUR_UPSOLVE_TOKEN}"

Now you may run npm i @upsolve-labs/sdk or yarn add @upsolve-labs/sdk to install the SDK.

Deploy Dashboard - Tailwind Setup

If you don’t already have Tailwind installed, please follow the setup instructions here. In your tailwind.config.js you will need to make 2 changes:

tailwind.config.js

module.exports = {
  content: [
    ...
    "./node_modules/@tremor/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@upsolve-labs/**/*.{js,ts,jsx,tsx}",
    "./node_modules/flowbite-react/lib/esm/**/*.{js,ts,jsx,tsx}",
  ],
  ...
  presets: [require("@upsolve-labs/sdk/tailwind.config.js")],
};

And make sure, per the instructions, that in your root.tsx file you have imported ./output.css with the output.css file you generated in step 4 of the Tailwind setup.

Deploy Dashboard - Configure global CSS

In your main layout.tsx or page.tsx, add this line to import the Upsolve CSS. For example, if you have a RootLayout it will look like this:

layout.tsx

"use client";
...
import '@upsolve-labs/common/styles/global.css';
...

export default function RootLayout({
  children,
}:
...

Workspace deployment

Deploy a full workspace instead of a single dashboard. You’ll need a tenant JWT and the workspace ID (available via the Deploy button in the Hub).For a complete walkthrough and advanced options, see Deploying Your Workspace.

Important: Changing the tenantJWT prop will trigger a complete dashboard refresh. The React component will:

Re-fetch all dashboard data with the new authentication context
Re-fetch filter options based on new tenant permissions
Re-render all charts with updated data access

This ensures the dashboard always reflects the current tenant’s permissions and data access, but can cause a brief loading state. Consider showing a loading indicator during JWT updates.

AnalyticsWorkspace.tsx

"use client";
import React from "react";
import { UpsolveWorkspace } from "@upsolve-labs/react";
import { useUser } from "@clerk/nextjs";

const AnalyticsWorkspace: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];

  return (
    <>
      {typeof upsolveToken === "string" && (
        <UpsolveWorkspace
          workspaceId={"ws_abc123"}
          tenantJWT={upsolveToken}
          tenantEditingPermissions={{
            addChart: true,
            addFilter: true,
            createChart: true,
            editCharts: true,
            removeChart: true,
            aiCharts: true,
          }}
          tabPlacement="top"
        />
      )}
    </>
  );
};

export default AnalyticsWorkspace;

Database Row-Level Security (RLS) Setup 🔒

If your Postgres, Redshift, or Supabase connection uses Row-Level Security policies, provide dbAuthToken to ensure proper row-level access within the workspace.

For Postgres and Redshift

Pass your user’s tenant identifier as dbAuthToken:

AnalyticsWorkspace.tsx

import { UpsolveWorkspace } from "@upsolve-labs/react";
import { useUser } from "@clerk/nextjs";

const AnalyticsWorkspace: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];
  const tenantId = user?.publicMetadata?.["tenantId"]; // Your user's tenant/company identifier

  return (
    <UpsolveWorkspace
      workspaceId="ws_abc123"
      tenantJWT={upsolveToken}
      dbAuthToken={tenantId}  // Tenant ID for RLS policies
    />
  );
};

dbAuthToken: The user-specific identifier that matches your RLS session variable (e.g., tenant ID, user ID, company code)

For Supabase

Retrieve and pass the Supabase session token:

AnalyticsWorkspace.tsx

import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  "https://your-supabase-project.supabase.co",
  "public-anon-key"
);

// ... inside component
const [dbAuthToken, setDbAuthToken] = React.useState<string | null>(null);
React.useEffect(() => {
  supabase.auth.getSession().then(({ data, error }) => {
    if (!error) setDbAuthToken(data.session?.access_token ?? null);
  });
}, []);

// Pass to UpsolveWorkspace when available
<UpsolveWorkspace
  workspaceId="ws_abc123"
  tenantJWT={upsolveToken}
  dbAuthToken={dbAuthToken ?? undefined}
/>

dbAuthToken: Access token from Supabase session used to evaluate RLS policies.

Key Points

Use workspaceId instead of dashboardId.
Global dashboards are read-only; tenant dashboards are editable per tenantEditingPermissions.
Tabs switch between global and tenant dashboards automatically; use tabPlacement="popover" for compact UI.

Getting the Workspace ID

Open the workspace in the Hub
Click Deploy
Copy the workspaceId from the integration snippet

All tenantEditingPermissions options

The following options control what tenants can do inside their personal dashboards in a workspace:

addChart: Allow tenants to add charts to their view-only dashboards
addFilter: Allow tenants to add filters that apply only to their view
createChart: Allow tenants to create new charts that appear only for them
createChartSQL: Allow tenants to create charts with SQL (requires createChart)
editCharts: Allow tenants to edit charts in their personal dashboards
removeChart: Allow tenants to remove charts from their view of a dashboard
readOnly: Make personal dashboards visible but read-only
disableTabs: Disable tabbed display in the SDK
aiCharts: Allow tenants to use AI-powered chart creation
editMarketplace: Allow tenants to edit marketplace charts
aiInsight: Allow access to the AI insights chat sidebar

Version Locking

You can lock a dashboard or workspace to a specific version using the version prop. This ensures that the component renders with a specific configuration, even if newer versions are published.

AnalyticsWorkspace.tsx

<UpsolveWorkspace
  workspaceId="ws_abc123"
  tenantJWT={upsolveToken}
  version={5}  // Lock to version 5
  tenantEditingPermissions={{
    addChart: true,
    createChart: true,
  }}
/>

Use cases for version locking:

Maintain consistency across different deployments
Test new dashboard versions before rolling them out to all users
Show different versions to different customer segments
Implement gradual rollouts of dashboard updates

If the version prop is not provided, the latest version will be rendered by default.

Deploy Dashboard - Deploy to Production

Make sure that your .npmrc or .yarnrc.yml values are provided to your deployment as env variables, otherwise the deployment will not work.

For enterprise features, look for the 🔒 symbol. These features are available in our Enterprise plan. Please contact us for more information.

Deploying AI Chat

There are two ways to deploy AI chat in your front end:

iFrame Embedding
Native React Component Embedding 🔒

iFrame Embedding
Native React Component Embedding 🔒

You’ll need to get the JWT for the current user and the agent ID to render the chat interface. The JWT is generated by following the steps in Backend Setup.

Getting the Agent ID

You can find your agent ID by visiting your agents at https://ai-hub.upsolve.ai/agents. The agent ID is visible in the URL when you click on an agent, or in the agent list view.

Authentication via JWT: Chat iframes use JWT tokens passed via query parameters for authentication, similar to dashboards. Users don’t need to be logged into the Hub - they just need a valid JWT token in the URL.

Important: Changing the JWT token in the iframe src will cause the browser to reload the entire iframe and reset the chat session. This happens automatically when:

The JWT expires and gets refreshed
User switches tenants/organizations
Tenant permissions are updated

Each iframe load starts a fresh chat session. Plan your token refresh strategy carefully to avoid interrupting active conversations.

Below is an example of deploying chat with JWT using Clerk middleware:

"use client";
import React from "react";
import { useUser } from "@clerk/nextjs";

const AIChatInterface: React.FC = () => {
  // Get the user information from Clerk and extract the Upsolve token from the metadata
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];
  const agentId = "your-agent-id"; // Replace with your agent ID

  // Embed the chat component into your app
  return (
    <>
      {upsolveToken != null && typeof upsolveToken === "string" && (
        <iframe
          id={agentId}
          title="AI Chat"
          width="100%"
          height="800"
          style={{ border: "none" }}
          src={`https://hub.upsolve.ai/share/chat/${agentId}?jwt=${upsolveToken}&theme=light`}
        />
      )}
    </>
  );
};

export default AIChatInterface;

Dashboard Query Parameters

The dashboard iframe supports the following query parameters:

Parameter	Type	Required	Description
`jwt`	string	Yes	Tenant JWT for authentication
`theme`	`light` \| `dark`	No	Visual theme
`version`	number	No	Lock to a specific dashboard version (defaults to latest)
`hideHeader`	boolean	No	Hide the header UI
`hideDownloadButton`	boolean	No	Hide the download button
`themeConfigs`	JSON string	No	Custom theme configuration
`dbAuthToken`	string	No	Database authentication token for RLS (see RLS section)
`filter_{key}`	any	No	Controlled filter values (e.g., `filter_region=US`)

Version Locking

You can lock an embedded dashboard to a specific version using the version parameter. This ensures that the dashboard renders with a specific configuration, even if newer versions are published.

<iframe
  id="c5da5cb3-fedb-4656-9170-0cc65c9db29a"
  title="Example Dashboard"
  width="1000"
  height="1000"
  src="https://hub.upsolve.ai/share/dashboard/c5da5cb3-fedb-4656-9170-0cc65c9db29a?theme=light&jwt=<upsolveToken>&version=5"
/>

Version locking is useful when: - You want to maintain consistency across deployments - You need time to test new dashboard versions before deploying them - Different customers should see different versions of the same dashboard

Chat Query Parameters

The chat iframe supports the following query parameters:

Parameter	Type	Required	Description
`jwt`	string	Yes	Tenant JWT for authentication
`prompt`	string	No	Initial prompt to start the conversation
`theme`	`light` \| `dark`	No	Visual theme
`isAdmin`	boolean	No	Enable admin features (default: `false`)
`hideHeader`	boolean	No	Hide the header UI
`themeConfigs`	JSON string	No	Custom theme configuration

Example with Initial Prompt

const AIChatWithPrompt: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];
  const agentId = "your-agent-id";
  const initialPrompt = "What were our top sales last quarter?";

  return (
    <iframe
      src={`https://hub.upsolve.ai/share/chat/${agentId}?jwt=${upsolveToken}&prompt=${encodeURIComponent(
        initialPrompt
      )}&theme=dark`}
      width="100%"
      height="800"
      style={{ border: "none" }}
    />
  );
};

Admin Mode

By default, the chat interface runs in end-user mode with simplified views. Set isAdmin=true to enable detailed tool execution information:

<iframe
  src={`https://hub.upsolve.ai/share/chat/${agentId}?jwt=${upsolveToken}&isAdmin=true`}
  width="100%"
  height="800"
/>

Understanding Session Reset on JWT Change

When the upsolveToken value changes, React re-renders the iframe with a new src URL. This causes the browser to completely reload the iframe and start a new chat session.

// Example: Token change triggers iframe reload and session reset
const AIChatInterface: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];

  // When upsolveToken changes, the chat session resets
  return (
    <iframe
      src={`https://hub.upsolve.ai/share/chat/abc?jwt=${upsolveToken}`}
      // ↑ Changing upsolveToken resets the entire conversation
    />
  );
};

Common scenarios that trigger session reset:

Automatic token refresh (every hour)
User switches between tenants/organizations
User logs out and back in
Tenant permissions are updated

To preserve chat history across token refreshes, consider: 1. Implementing session persistence on your backend 2. Storing conversation history outside the iframe 3. Refreshing tokens during natural conversation breaks 4. Warning users before token expiration

Import Upsolve AI SDK

If you haven’t already, ask the Upsolve AI team for “a key to the private NPM library”. Use the key in your .npmrc or .yarnrc file. You can then import the SDK into your application.See the Dashboard Deployment section for detailed setup instructions.Once configured, install the SDK:

npm i @upsolve-labs/sdk
# or
yarn add @upsolve-labs/sdk

Deploy Chat - Tailwind and CSS Setup

If you haven’t already set up Tailwind and global CSS for the Upsolve SDK, follow these steps:Tailwind Configuration (tailwind.config.js):

tailwind.config.js

module.exports = {
  content: [
    ...
    "./node_modules/@tremor/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@upsolve-labs/**/*.{js,ts,jsx,tsx}",
    "./node_modules/flowbite-react/lib/esm/**/*.{js,ts,jsx,tsx}",
  ],
  ...
  presets: [require("@upsolve-labs/sdk/tailwind.config.js")],
};

Global CSS Import (layout.tsx):

layout.tsx

"use client";
import '@upsolve-labs/common/styles/global.css';

See the Dashboard Deployment section for complete setup details.

Deploy Chat Component

Use the UpsolveChat component to embed AI chat directly in your React application.

Important: Changing the tenantJWT prop will reset the chat session. The React component will:

Clear the current conversation
Re-fetch agent configuration with new authentication
Start a fresh session with updated data access

This ensures the chat reflects the current tenant’s permissions, but will interrupt ongoing conversations.

AIChat.tsx

"use client";
import React from "react";
import { UpsolveChat } from "@upsolve-labs/sdk";
import { useUser } from "@clerk/nextjs";

const AIChat: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];

  return (
    <>
      {typeof upsolveToken === "string" && (
        <UpsolveChat
          tenantJWT={upsolveToken}
          agentId="your-agent-id"
          prompt="How can I help you today?"
        />
      )}
    </>
  );
};

export default AIChat;

Props

Prop	Type	Required	Description
`tenantJWT`	string	Yes	JWT token for authentication
`agentId`	string	No	Agent ID (fetches first agent if not provided)
`prompt`	string	No	Initial prompt to start the conversation
`apiHostOverride`	string	No	Custom API endpoint (default: `https://api.upsolve.ai`)
`useLocalApi`	boolean	No	Use localhost for testing (default: `false`)

Example with Custom Prompt

<UpsolveChat
  tenantJWT={upsolveToken}
  agentId="your-agent-id"
  prompt="Show me sales data for Q4 2024"
/>

Auto-selecting Agent

If you don’t specify an agentId, the component will automatically use the first available agent for the organization:

<UpsolveChat
  tenantJWT={upsolveToken}
  // No agentId - uses first agent automatically
/>

Deploy Chat - Deploy to Production

Make sure that your .npmrc or .yarnrc.yml values are provided to your deployment as env variables, otherwise the deployment will not work.

For enterprise features, look for the 🔒 symbol. These features are available in our Enterprise plan. Please contact us for more information.

Analytics Layer

Data Connection

Charts

Dashboards

Filtering

Data Permissioning

Scheduled Reporting

Sharing & Export

Customize

Deployment

Understanding JWT Changes and Iframe Refresh

For Postgres and Redshift

For Supabase

For Postgres and Redshift

For Supabase

Deploying AI Chat

Getting the Agent ID

Dashboard Query Parameters

Version Locking

Chat Query Parameters

Example with Initial Prompt

Admin Mode

Understanding Session Reset on JWT Change

Props

Example with Custom Prompt

Auto-selecting Agent

Analytics Layer

Data Connection

Charts

Dashboards

Filtering

Data Permissioning

Scheduled Reporting

Sharing & Export

Customize

Deployment

Documentation Index

​Understanding JWT Changes and Iframe Refresh

​For Postgres and Redshift

​For Supabase

​For Postgres and Redshift

​For Supabase

​Deploying AI Chat

​Getting the Agent ID

​Dashboard Query Parameters

​Version Locking

​Chat Query Parameters

​Example with Initial Prompt

​Admin Mode

​Understanding Session Reset on JWT Change

​Props

​Example with Custom Prompt

​Auto-selecting Agent

Understanding JWT Changes and Iframe Refresh

For Postgres and Redshift

For Supabase

For Postgres and Redshift

For Supabase

Deploying AI Chat

Getting the Agent ID

Dashboard Query Parameters

Version Locking

Chat Query Parameters

Example with Initial Prompt

Admin Mode

Understanding Session Reset on JWT Change

Props

Example with Custom Prompt

Auto-selecting Agent