Skip to main content
Your platform shows an app your builders create in an iframe. If the app asks people to sign in, it opens on its own sign-in page inside that frame. To open it already signed in as the end user looking at it, your server mints a one-time sign-in token for them and puts it on the iframe URL. Nothing inside the app changes.

​
Deciding whether you need a token

An app’s visibility decides whether it asks people to sign in, and so whether you need a token at all. Set it with public_settings when you create the app. Without sign-in, the app can’t tell who’s looking at it, so anything that belongs to one person, such as their own saved data, doesn’t work. Learn more about app visibility.

​
Signing the end user in

Before you begin: Create a workspace API key in your enterprise workspace with the Provision app users and Mint embed sign-in tokens permissions. Set App access to All current and future apps, since your builders keep creating new ones. Send it from your server as api_key: <key>, together with X-Active-Workspace-Id: <workspace id>.
1

Provision the end user

Send POST /api/apps/{app_id}/users/provisions with the end user’s email and one of the app’s roles:
This gives them access to the app. It’s idempotent, so you can call it before every mint. The response’s status is created the first time and exists after that.Use the email your platform signed the end user in with. Never take it from the browser, or anyone could open an app as anyone else.
2

Mint a sign-in token

Send POST /api/apps/{app_id}/embed-tokens with the same email, and the version of the app you want to show:
The response carries embed_url, the address of that version with the token already on it, and expires_in, which is 60 seconds.
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 works only once, so mint a new one each time you load the frame.

​
Choosing which version to show

Match target to what the end user should see:
  • An app you’ve published: Use live_site.
  • An app you haven’t published: Use latest_preview, which also shows builders their changes as soon as a build finishes.
  • The builder’s preview while a build runs: Use live_preview.

​
Errors

Minting returns errors as {"error": {"code", "message", "details"}}. The reference integration does all of this in embedSession.ts.

​
See also