Skip to main content
You can show an app inside your platform in an iframe. If the app asks people to sign in, they see its sign-in page inside the frame. To skip that and open the app already signed in as the end user, your server can create a one-time sign-in token and add it to the iframe URL. The app itself doesn’t need any changes.

​
Decide if you need a token

You need a sign-in token only when the app asks people to sign in. That depends on the app’s visibility, which you set with public_settings when you create the app. If you don’t need a token, load the app’s address in the iframe. If you do, mint one for each end user so they skip the sign-in page.
An app with no login can’t tell visitors apart, so features that depend on who someone is, such as profiles or data saved for each person, don’t work. Learn more about app visibility.

​
Let the app load in a frame

A new app refuses to load inside an iframe on another site: prevent_iframe_embedding defaults to true, and a clone or a remix starts that way too. Set it to false in the Create app call when you plan to embed the app. For an app that already exists, including a remix, send { "prevent_iframe_embedding": false } to Update security headers, which applies to the published app right away. Preview URLs aren’t affected by the setting.
A remix copies the source app in the background and, when it finishes, writes the source’s public_settings and custom_instructions over anything you set in the meantime. Poll Get app until status.state is no longer processing before you configure a remix, then read the settings back.

​
Give the app your platform’s data

An app your builders create often needs data that only your platform holds, under your platform’s permissions. Two patterns work, and both are things your platform builds around the frame rather than Base44 features:
  • The host page answers the app’s requests. The app asks the page that frames it over postMessage, and the page answers from its own session. The app holds no credential, and the identity is whoever is signed in to your platform. The reference integration does this: it mints a short-lived viewer token for the current user and posts it into the frame when the app asks. The app then works only inside your page.
  • The host issues a short-lived signed token. Your platform issues a token scoped to that app and the queries you granted it, and the app calls your platform’s API directly. The request carries no Base44 session for the person using the app, so anything inside Base44 that is per user, such as a connector that user connected, can’t resolve for it.
In both cases, say in the app’s custom instructions how the app gets its data and what’s read-only.

​
Sign the end user in

Your server signs an end user in with two calls. The first gives them access to the app, and the second returns the app’s address with a sign-in token on it. Then you load that address in your iframe.
Before you begin: Use the personal access token your integration already builds with. Send it from your server as Authorization: Bearer <token>, together with X-Active-Workspace-Id: <workspace id>.
To use a workspace API key instead, create one in your enterprise workspace and send it as api_key: <key>, together with X-Active-Workspace-Id: <workspace id>. Give it:
  • Permissions: Provision app users and Mint embed sign-in tokens.
  • App access: All current and future apps, since your builders keep creating new ones.
1

Provision the end user

Send POST /api/apps/{app_id}/users/provisions with the end user’s email and a role. Apps have admin and user roles by default, and you can add your own:
This gives them access to the app. It’s idempotent, so you can call it before every mint. The response returns the end user’s email and role, and a status that is created the first time and exists after that. If the end user already existed, role is the role they already had.
Take the email from your own server-side session, never from a value the browser sends. The token signs in whichever email you send, so if that email comes from the browser, an end user could send someone else’s and open the app as them.
2

Mint a sign-in token

Send POST /api/apps/{app_id}/embed-url with the same email and a target, which is the version of the app you want to show:
The response returns two fields. The embed_url field is the address of that version with the token already on it. The expires_in field is how many seconds the token lasts.
3

Load the URL in your iframe

Set the iframe’s src to embed_url, and the app opens signed in as the end user. A token is short lived and works only once, so mint a new one each time you load the frame.
If your workspace has an embedding policy set to Only these sites, add your platform’s website to its list, or the app won’t load in your iframe. With No one, no website can embed your apps.
The reference integration does all three steps in embedSession.ts, using a workspace API key.

​
Errors

If a call fails, the response includes an error with a code, a message, and details. Use the code to tell what went wrong. These are the errors minting a token can return.

​
See also