Embed Sessions

An embed session is the short-lived grant that lets a RealityTwin render inside your page. Your backend creates one through the RealityConnect API, forwards the browser-safe values to your front-end, and your front-end hands them to the SDK. This page is the reference for those two endpoints, for every field they return, and for the one value you have to assemble yourself: the iframe URL.

---

The two session endpoints

Both operations live on the twin context and are published in the interactive API reference, flagged experimental.

Method	Path	Body
GET	{api_url}/v1/twin/{contextId}/embed/create-session	None
POST	{api_url}/v1/twin/{contextId}/embed/refresh-session	{ "refreshToken": "<base64 refresh token>" }

{api_url} is your regional API base, which already ends in /realityconnect-api. A complete call therefore looks like:

GET https://api-ue1.prevu3d.com/realityconnect-api/v1/twin/{contextId}/embed/create-session
Authorization: Bearer {access_token}

{contextId} is the id of the twin you want to embed. RealityPlan is not supported here.

Caution

Create and refresh sessions from your own backend. Your OAuth client secret and the refresh token must never reach the browser.

Required scopes

Both operations require two scopes on the same access token:

Scope	Why
read:twin	Read the twin the session targets
embed:twin	Mint an embed session for it

A token holding only one of the two receives 403 Forbidden with Insufficient OAuth scopes. Add both to your OAuth application before you start; see the Client Credentials Flow guide.

Embed sessions also use a dedicated, tighter rate-limit budget than the rest of the API, so create a session per viewing session rather than per page render.

The create-session response

{
  "iframeUrl": "https://embed.prevu3d.com/reality-twin",
  "token": "eyJhbGciOiJFUzUxMi...",
  "refreshToken": "ZXhhbXBsZS1yZWZyZXNoLXRva2Vu",
  "expiresAt": "2026-09-04T13:55:00.000Z",
  "apiUrl": "https://api-ue1.prevu3d.com/reality-twin"
}

Field	What it is	SDK config
iframeUrl	The base URL of the embed viewer. Complete it before use — see Building the iframe URL.	iframeUrl, after you append the embed route
token	The signed session JWT. The SDK requires it; the embedded twin authenticates with it.	platformJWT
refreshToken	Base64 secret paired with this session. Keep it on your backend.	—
expiresAt	ISO 8601 timestamp to refresh the session by — a few minutes before token itself stops being accepted.	—
apiUrl	The regional RealityTwin backend the embedded twin talks to (…/reality-twin). Not the {api_url} you called above — the session endpoints do not live on it.	backendUrl

refresh-session returns the same shape without iframeUrl and apiUrl. You only need those two once: iframeUrl is constant for the environment, and apiUrl is constant for your organization’s region.

Note

expiresAt is a deliberately conservative estimate computed when the response is built, and it lands a few minutes before the token’s own expiry. Treat it as the moment to refresh, not as the exact instant the token stops working.

Building the iframe URL

iframeUrl is a base URL, not a finished src. It is the same constant for every twin within an environment — in production, https://embed.prevu3d.com/reality-twin. Append the embed route to it:

const src = `${session.iframeUrl}/embed`;
// https://embed.prevu3d.com/reality-twin/embed

The twin id is not needed in the URL — the session token already identifies the twin, and the viewer reads it from there.

Join the two with exactly one slash: iframeUrl has no trailing slash, so `${iframeUrl}/embed` is correct.

Hand the completed URL to the SDK:

RealityConnectEmbed.init({
  iframeUrl: `${session.iframeUrl}/embed`,
  backendUrl: session.apiUrl,
  platformJWT: session.token,
  elementId: 'twin-container',
});

Caution

Passing iframeUrl through unchanged does not load the twin viewer at all. The value has no trailing slash, and on the embed host that exact path is served by a different application — only paths below it reach the viewer. The SDK’s handshake then has nothing to talk to, so onReady never fires and the SDK reports TWIN_TIMEOUT once its ready timeout elapses.

The token is never in the URL

The session JWT travels to the iframe over the SDK’s INIT_CONFIG postMessage handshake, as the platformJWT config value. Do not append it to the iframe URL as a query parameter — the embedded twin does not read one, and putting a live credential in a URL exposes it to browser history, referrer headers and server logs.

For the same reason, the embed page expects to run inside the SDK’s iframe. Pasting a completed URL into a browser tab on its own will not load a twin, because nothing is there to hand it the token and the backend URL.

Keeping the session alive

Sessions are short-lived. Before expiresAt, call refresh-session from your backend with the stored refreshToken, persist the new one, and pass the new token to the running SDK with twin.updateAccessToken(newAccessToken) — the iframe does not need to be recreated. See Step 4 of Getting Started for the full pattern.

Next steps

• Getting Started — the end-to-end integration this reference supports.
• Client Credentials Flow — how to obtain the access token these calls need.
• Interactive API reference — the published schema for both operations.