> ## Documentation Index > Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt > Use this file to discover all available pages before exploring further. # Embed Upsolve in your product > One API key on your server, one call per sign-in, one iframe. Your users get an Upsolve **workspace** (the AI chat) or **application** (dashboards) inside your product, signed in as themselves and limited by row-level security to their own data. It takes three things: 1. An **API key**, kept on your server. 2. **One backend call** per sign-in — [`POST /v1/api/projects/embed-token`](/api-reference/endpoint/create-embed-token) — which returns a token for the user. 3. 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: ```text Setup prompt theme={null} 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: - Project 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 Content-Type: application/json { organizationId: "", projectId: "", 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": "", "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. as {{organization.}} and user.properties. as {{user.}}. Send every property the workspace's RLS rules read, filled from this app's own data for the signed-in user. 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: 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](https://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. ```bash theme={null} curl https://api.upsolve.ai/v1/api/projects/embed-token \ -H "Authorization: Bearer $UPSOLVE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "organizationId": "", "projectId": "", "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" }' ``` ```json Response theme={null} { "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.}}`. 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.}}`. Merged the same way, so a sign-in that sends only `email` cannot wipe a key set by an import or in the Hub. | | `user.userRoleId` | No | A [project user role](/api-reference/endpoint/list-project-user-roles). Grants dashboard editing (adding charts and filters). 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`. | The same call in Node: ```ts theme={null} 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: "", projectId: "", 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 ```html theme={null} ``` The embed serves the workspace's **production** version: publish the workspace and promote a version first. ```html theme={null} ``` Add `&dashboardId=` to open one dashboard without the sidebar. `/share/dashboard/?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](#keep-the-token-out-of-the-url). * If your app sends a `Content-Security-Policy`, add `https://ai-hub.upsolve.ai` to `frame-src`. A minimal React page: ```tsx theme={null} export function AnalyticsPage() { const [src, setSrc] = useState(null); useEffect(() => { let active = true; let timer: ReturnType | 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//?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 ?