Embed Upsolve in your product

Embedding puts the agent you built in your workspace inside your own product. Your users open a page in your app and get a complete analytics experience, signed in as themselves and seeing only their own data.

An Upsolve workspace embedded in a SaaS app called YourApp: the side panel lists canvases and past chats, and the chat shows a question answered with a Profit by Region donut chart

What your users get

An analytics agent to ask. Questions in plain English, answered with charts, tables and a written summary, using all the context, tests and rules you set up in the workspace.
Their own conversations. Past chats stay in the side panel, so they can pick one back up. They can also share a chat.
Favorites. Any answer can be saved with Add to favorites, and opened again later.
Canvases. Dashboards they build from their saved answers, plus any canvas you share with all your users. See Embed Canvases.
Their own data, always. Every answer and chart runs under the data governance rules you set, with the properties you send when they sign in.

It looks like part of your product: the embed takes your workspace’s theme, and you can set its wording, starter questions and light or dark mode with iframe options.

Two ways to embed

	Embed the workspace (this page)	Embed a canvas link
What users get	The full experience above: chat, favorites and canvases	One read-only canvas
Whose data	Each user’s own	The canvas owner’s, the same for everyone
Sign-in	Your backend gets a token for each user	None: a link, with an optional passkey
Use it for	Analytics inside your product	A public board, or a report for one client

Most products want the workspace embed. To give every customer the same dashboard with their own numbers, build it as a canvas and share it inside the workspace embed: see Embed Canvases.

How it works

It takes three things:

An API key, kept on your server.
One backend call per sign-in — POST /v1/api/projects/embed-token — which returns a token for the user.
An iframe that carries the token.

Set it up with an AI coding assistant

The fastest way: open your workspace’s Deploy page in Upsolve, click Create an API key, and copy the Setup prompt. It already contains your organization, project and workspace ids and the exact properties your row-level security reads. Paste it into Claude Code, Cursor or any coding assistant working in your product’s codebase. Or copy this one and replace the values in angle brackets — all of them are on the Deploy page:

Setup prompt

Embed an Upsolve AI chat in this app, signed in as the current user. Do the whole integration: a backend endpoint, a page with the iframe, and a navigation entry for it.

## Values (from the Upsolve Deploy page — use them as constants)
- Upsolve API: https://api.upsolve.ai
- Embed host: https://ai-hub.upsolve.ai
- Upsolve organization ID: <ORGANIZATION_ID>
- Project ID: <PROJECT_ID>
- Workspace ID: <WORKSPACE_ID>

## The one secret
An Upsolve API key. I create it at https://ai-hub.upsolve.ai/account/settings?tab=developer and give it to the server as the environment variable UPSOLVE_API_KEY. Read it from the environment on the server only — add it to this app's server env config (and to .env.example without a value). Never send it to the browser, put it in client code, or log it.

## 1. Backend
Add an authenticated server endpoint (for example GET /api/upsolve/embed-token) behind this app's existing auth. Take the signed-in user and the customer/tenant/account they belong to from the session, never from the request. It makes one call:

POST https://api.upsolve.ai/v1/api/projects/embed-token
Authorization: Bearer <UPSOLVE_API_KEY>
Content-Type: application/json
{
  organizationId: "<ORGANIZATION_ID>",
  projectId: "<PROJECT_ID>",
  organization: {
    externalId: tenant.id, // your id for the customer this user belongs to
    name: tenant.name,
    properties: { tenant_id: tenant.id },
  },
  user: {
    externalId: user.id, // your id for the user
    name: user.email,
    properties: { email: user.email },
  },
  expiration: "1h",
}

The response is { "status": "success", "data": { "token": "...", "expiresAt": "<ISO time>", "projectUserId": "...", "projectOrganizationId": "..." } }. Return { token, expiresAt } to the browser. The call is idempotent — it creates the organization and the user the first time, merges in the properties you send after that (a key sent as null is removed, a key left out is kept), and writes nothing when nothing changed — so call it every time the page loads. "externalId" is this app's own id for the tenant and for the user (any string). If the app has no tenants, use one constant externalId for the organization. "expiration" may be 5m, 15m, 30m, 1h, 2h, 6h, 12h, 24h or 7d.

## 2. Row-level security
Upsolve row-level security (RLS) reads organization.properties.<key> as {{organization.<key>}} and user.properties.<key> as {{user.<key>}}. Send every property the workspace's RLS rules read, filled from this app's own data for the signed-in user. Always send user.properties.email as the signed-in user's email address: "email" is a reserved property, the address Upsolve emails that user at (for example when they press a canvas button that sends them a report). If it is not obvious which field holds a value, ask me rather than guessing: a wrong value shows a user someone else's data.

## 3. Frontend
Add a page (and a link to it in the app's navigation) that calls the endpoint above and renders:

<iframe title="AI Chat" style="border:none;width:100%;height:100%" src="https://ai-hub.upsolve.ai/share/workspace/<PROJECT_ID>/<WORKSPACE_ID>?jwt=<URL-encoded token>"></iframe>

Give it the page's full height. Show a loading state while the token is fetched, and an error with a Retry button if it fails. Fetch a new token once about 80% of its lifetime has passed (never sooner than 30 seconds), and update the src (that reloads the chat; its history is kept). If this app sends a Content-Security-Policy, add https://ai-hub.upsolve.ai to frame-src.

## 4. Check
Sign in as users from two different tenants and confirm each one sees only their own data.

Full reference: https://docs.upsolve.ai/embedding

The rest of this page is what that prompt does, step by step.

1. Get an API key and your ids

API key. In Upsolve, open Account settings → Developer (ai-hub.upsolve.ai/account/settings?tab=developer) and generate a key. Store it on your server, for example as UPSOLVE_API_KEY. It must never reach the browser.
Ids. A workspace’s Deploy page lists the Organization ID (your Upsolve organization), Project ID and Workspace ID, each with a copy button. An application’s id is on its Deploy panel.

2. Sign your users in

Call embed-token from your backend whenever a user opens a page with the embed. The first call for a customer creates them as a project organization, the first call for a user creates them as a project user, and every later call finds the same rows by your ids and merges in the properties you send. A call that changes nothing writes nothing, so there is nothing to register in advance and nothing to store.

curl https://api.upsolve.ai/v1/api/projects/embed-token \
  -H "Authorization: Bearer $UPSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<ORGANIZATION_ID>",
    "projectId": "<PROJECT_ID>",
    "organization": {
      "externalId": "acme",
      "name": "Acme Inc",
      "properties": { "tenant_id": "acme" }
    },
    "user": {
      "externalId": "user-42",
      "name": "ada@acme.com",
      "properties": { "email": "ada@acme.com" }
    },
    "expiration": "1h"
  }'

Response

{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresAt": "2026-10-10T13:00:00.000Z",
    "projectUserId": "6f1c...",
    "projectOrganizationId": "b52e...",
    "userCreated": false,
    "organizationCreated": false
  }
}

Field	Required
`organizationId`	With an Account-settings key	Your Upsolve organization’s id, from the Deploy page — not your customer. Keys from Account settings are user-scoped and are refused without it; an organization-bound key ignores it, so it is always safe to send.
`projectId`	Yes	The project the workspace or application belongs to.
`organization.externalId`	Yes	Your id for the customer the user belongs to. Any string. With no customers of your own, use one constant.
`organization.name`	No	Shown in Upsolve. Defaults to `externalId`.
`organization.properties`	No	Read by RLS as `{{organization.<key>}}`. Merged into what is stored: a key you send replaces its value, a key sent as `null` is removed, a key you leave out is kept.
`user.externalId`	Yes	Your id for the user, unique within their organization.
`user.name`	No	Shown in Upsolve (chat history, favourites). Defaults to `externalId`.
`user.properties`	No	Read by RLS as `{{user.<key>}}`. Merged the same way, so a sign-in that sends only `email` cannot wipe a key set by an import or in the Hub. `email` is reserved: set it to the user’s email address.
`user.userRoleId`	No	A project user role: what the user may do on an Applications dashboard — see Roles and permissions. Canvases don’t use it. Set on every call that sends it; leave it out to keep the user’s current role (none, for a new user, who views and chats); `null` removes it.
`user.defaultUserRoleId`	No	The role a new user gets when `userRoleId` is left out. Never applied to an existing user, so a role you change in Upsolve survives their next sign-in.
`expiration`	No	`5m`, `15m`, `30m`, `1h` (default), `2h`, `6h`, `12h`, `24h` or `7d`.
`environment`	No	`production` (the default) or one of your project’s environments, such as `staging`: which deployed version of the workspace, and which databases, the user is served. Set when the organization is first created.

The same call in Node:

export async function getUpsolveEmbedToken(user, tenant) {
  const response = await fetch("https://api.upsolve.ai/v1/api/projects/embed-token", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.UPSOLVE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      organizationId: "<ORGANIZATION_ID>",
      projectId: "<PROJECT_ID>",
      organization: { externalId: tenant.id, name: tenant.name, properties: { tenant_id: tenant.id } },
      user: { externalId: user.id, name: user.email, properties: { email: user.email } },
      expiration: "1h",
    }),
  });
  if (!response.ok) throw new Error(`Upsolve embed-token: ${response.status}`);
  const { data } = await response.json();
  return { token: data.token, expiresAt: data.expiresAt };
}

Take the user and tenant from your own session, never from the request, and return only token and expiresAt to the browser.

3. Embed the iframe

Workspace (AI chat)
Application (legacy)

<iframe
  title="AI Chat"
  style="border: none; width: 100%; height: 100%;"
  src="https://ai-hub.upsolve.ai/share/workspace/<PROJECT_ID>/<WORKSPACE_ID>?jwt=<token>"
></iframe>

The embed serves the workspace’s production version: save a version and promote it first.

<iframe
  title="Analytics"
  style="border: none; width: 100%; height: 100%;"
  src="https://ai-hub.upsolve.ai/share/application/<APPLICATION_ID>?jwt=<token>"
></iframe>

Add &dashboardId=<id> to open one dashboard without the sidebar. /share/dashboard/<dashboardId>?jwt=… does the same when you only have a dashboard’s id.

URL-encode the token.
Fetch a new token once about 80% of its lifetime has passed (never sooner than 30 seconds) and set it as the new src. That reloads the embed; a workspace keeps the user’s conversation history. To replace it without a reload, use token handoff.
If your app sends a Content-Security-Policy, add https://ai-hub.upsolve.ai to frame-src.

A minimal React page:

export function AnalyticsPage() {
  const [src, setSrc] = useState<string | null>(null);

  useEffect(() => {
    let active = true;
    let timer: ReturnType<typeof setTimeout> | undefined;
    const load = async () => {
      const { token, expiresAt } = await fetch("/api/upsolve/embed-token").then((r) => r.json());
      if (!active) return; // the page was left while the request was in flight
      setSrc(`https://ai-hub.upsolve.ai/share/workspace/<PROJECT_ID>/<WORKSPACE_ID>?jwt=${encodeURIComponent(token)}`);
      // Refresh once 80% of the token's life has passed — never sooner than 30 seconds.
      const lifetime = Date.parse(expiresAt) - Date.now();
      timer = setTimeout(load, Math.max(lifetime * 0.8, 30_000));
    };
    load();
    return () => {
      active = false;
      clearTimeout(timer);
    };
  }, []);

  return src ? <iframe title="AI Chat" src={src} style={{ border: "none", width: "100%", height: "100%" }} /> : null;
}

Row-level security

The properties you send are what the workspace’s or application’s row-level security rules filter on. A rule like

SELECT * FROM orders WHERE tenant_id = '{{organization.tenant_id}}'

shows each user only their own customer’s orders: {{organization.tenant_id}} is replaced with organization.properties.tenant_id, and {{user.<key>}} with user.properties.<key>. The Deploy page’s setup prompt lists the exact keys your production rules read. Write the rules in the workspace’s Data Model — see Data Governance — and check them by signing in as users of two different customers. A property the rules read but the user does not have makes the query fail rather than return everything.

Reserved user properties

One user property name means something to Upsolve beyond RLS:

Property	Holds	Used by
`email`	The user’s own email address, e.g. `ada@acme.com`.	Rules that email the person they act for, such as a canvas button that sends whoever presses it the report as a PDF, or a schedule that emails its owner. The email goes to this address and nowhere else.

Send email for every user who should be able to receive these emails. A rule that emails the person it acts for does not send for a user whose email is missing, empty or not one valid address: their button says so instead. Upsolve never takes the address from a row of data or from what a user types, so the only way to change where it goes is to change this property. You can still use email in RLS as {{user.email}}.

Database-native RLS (Postgres, Redshift, Supabase)

If your database enforces row-level security itself, pass the value its policies read as dbAuthToken on an application embed: …/share/application/<APPLICATION_ID>?jwt=<token>&dbAuthToken=<value>. For Postgres and Redshift it is the value your session variable expects (a tenant or user id); for Supabase it is the user’s session access token (supabase.auth.getSession()). See RLS & Schema Filtering.

Environments

A project can have environments besides production (staging, say), each serving its own deployed version of the workspace on its own databases. You manage them under Project settings → Environments; see Environments for how they work. A user’s environment decides which one they get, and the sign-in call names it:

"environment": "staging"

Production is the default. A production integration leaves the field out.
The same externalId in another environment is a separate organization, with its own users and properties, so your staging build can sign in with production’s tenant ids.
It is fixed when the organization is first created. A user is always in their organization’s environment, and a later call never moves anyone. To move an organization and its users, edit it in Upsolve and use Move to environment.
Send it from the deployment it belongs to. Read it from that deployment’s server config (for example UPSOLVE_ENVIRONMENT) rather than hard-coding it, so your production deployment leaves it out.
An environment serves nothing until a version is deployed to it, from the workspace’s Deploy to… menu. Until then its users’ embed shows an error, never production’s version.

On the workspace’s Deploy page, switch the header’s Environment control to the environment you are setting up. The prompt and snippets then fill in environment for it.

Keep the token out of the URL

A token in ?jwt= is written to every access log between your user and Upsolve. With token handoff the iframe asks your page for it over postMessage instead, and a refreshed token replaces the old one without reloading the embed. It works on /share/workspace, /share/application and /share/dashboard. Open the iframe with tokenHandoff=true and your page’s origin, and no jwt:

const EMBED_ORIGIN = "https://ai-hub.upsolve.ai";
const iframe = document.getElementById("upsolve");

// Attach before setting the src.
window.addEventListener("message", async (event) => {
  if (event.origin !== EMBED_ORIGIN || event.source !== iframe.contentWindow) return;
  if (event.data?.type === "embed:ready" && event.data.awaitingToken) {
    const { token } = await fetch("/api/upsolve/embed-token").then((r) => r.json());
    iframe.contentWindow.postMessage({ type: "embed:set-token", v: 1, token }, EMBED_ORIGIN);
  }
});

iframe.src =
  `${EMBED_ORIGIN}/share/workspace/<PROJECT_ID>/<WORKSPACE_ID>?tokenHandoff=true` +
  `&parentOrigin=${encodeURIComponent(location.origin)}`;

Post embed:set-token again with a fresh token before expiresAt to replace it in place. The iframe accepts a token only from the declared parentOrigin and its own parent window, keeps it in memory only, and shows No token received from the embedding page after 15 seconds without one. The full protocol — live filter sync and auto-height included — is in iframe messaging.

Iframe options

Workspace (AI chat)
Application (legacy)

Parameter
`prompt`	A first message, sent when the chat opens.
`theme`	`light` or `dark`.
`placeholderOverrides`	JSON: any of `userName`, `assistantName`, `inputPlaceholder`, `thinkingPlaceholder`, `disclaimerText`.
`exampleQuestions`	JSON array of up to three starter questions for the welcome screen.
`nav`	`favorites` or `canvas` to open that panel.
`tokenHandoff`, `parentOrigin`	See token handoff.

Parameter
`dashboardId`	Open this dashboard, with the sidebar and tabs hidden.
`hideHeader`, `hideDownloadButton`	`true` hides the dashboard title, or the CSV download.
`transparent`	`true` renders on a transparent background.
`filter_<key>`	A controlled filter’s value — see URL filter parameters.
`f_<source>.<table>.<column>`	An omnibar filter’s value — same page.
`parentOrigin`, `autoHeight`	Live filter sync and content height over `postMessage` — see iframe messaging.
`dbAuthToken`	See database-native RLS.
`tokenHandoff`	See token handoff.

An application’s colors and fonts come from its theme in Upsolve; there is no theme parameter.

Troubleshooting

What you see	Why, and the fix
`400 organizationId is required when using a user-scoped API key`	Keys from Account settings are user-scoped. Send `organizationId` (the Deploy page’s Organization ID) in the body.
`401`	The API key is missing, mistyped or revoked.
`403`	The key’s owner must be an owner, admin or member of the organization; a read-only member’s key cannot sign users in.
`404 Project not found or does not belong to this organization`	`projectId` and `organizationId` don’t match. Copy both from the same Deploy page.
`404 User role not found…`	`userRoleId` belongs to another project, or was deleted.
`400` naming `expiration`	Use one of the lifetimes listed above.
The embed says Session expired	The token expired. Fetch a new one before `expiresAt`.
The embed says This workspace has not been published	Save a version and promote it to production. With environments, deploy a version to Production from Deploy to….
The embed says This workspace has no version deployed to staging	The user is in that environment and nothing is deployed there yet. Deploy a version to it from Deploy to….
`404 This project has no "…" environment`	`environment` names an environment the project does not have. Copy the slug from Project settings → Environments.
`400` saying environments are not enabled	Your organization has no environments yet. Leave `environment` out, or send `production`.
A user sees no data, or an error about a property	The RLS rules read a property the user was not sent. Compare your `properties` with the keys on the Deploy page.

Lower-level endpoints

embed-token does in one call what register-organization, register-user and user-token do in three. Those still work, for integrations that manage Upsolve’s ids themselves; a token from user-token goes in the iframe the same way. To let the chat call your own API as the signed-in user, using the same properties you send here, see Let Upsolve act as your users.

Get Started

Core Concepts

Build the Context

Develop

Monitor

Ship

End-User Experience

Applications (legacy)

Embed Upsolve in your product

What your users get

Two ways to embed

How it works

Set it up with an AI coding assistant

1. Get an API key and your ids

2. Sign your users in

3. Embed the iframe

Row-level security

Reserved user properties

Environments

Keep the token out of the URL

Iframe options

Troubleshooting

Lower-level endpoints

​What your users get

​Two ways to embed

​How it works

​Set it up with an AI coding assistant

​1. Get an API key and your ids

​2. Sign your users in

​3. Embed the iframe

​Row-level security

​Reserved user properties

​Environments

​Keep the token out of the URL

​Iframe options

​Troubleshooting

​Lower-level endpoints

What your users get

Two ways to embed

How it works

Set it up with an AI coding assistant

1. Get an API key and your ids

2. Sign your users in

3. Embed the iframe

Row-level security

Reserved user properties

Environments

Keep the token out of the URL

Iframe options

Troubleshooting

Lower-level endpoints