SDK Options · Moshpit Docs

API Reference

SDK Options

Every field accepted by Moshpit.viewer(...), Moshpit.editor(...), createViewerEmbed(...), and createEditorEmbed(...).

The viewer and editor share most options. Editor Embeds are available on all plans. The differences are at the bottom of this page.

Common options

These apply to both Moshpit.viewer and Moshpit.editor.

Field	Type	Description
publicKey Required	string	The integration public key (`mpk_...`). Identifies which integration is mounting the embed.
origin	string default "https://moshpit.studio"	Override the iframe origin. Useful only if you self-host or hit a staging environment.
width	string \| number default "100%"	iframe `width`. A number is interpreted as pixels.
height	string \| number default "100%"	iframe `height`. A number is interpreted as pixels.
title	string	iframe `title` attribute. Improves screen-reader experience.
loading	"eager" \| "lazy" default "lazy"	Sets the iframe `loading` attribute. With `"lazy"`, the browser chooses when the iframe is near enough to start loading and may fetch it before it enters the viewport. Use `"eager"` to start fetching immediately.
referrerPolicy	HTMLIFrameElement['referrerPolicy'] default "strict-origin-when-cross-origin"	Sets the iframe `referrerpolicy` for the host-page to embed-page navigation. Viewer Embed pages separately use `no-referrer` for their own Scene-file and API requests.
background	string default "#000"	CSS background color visible while the iframe loads.
borderRadius	string \| number	CSS border-radius. Useful for rounded corners on cards.
responsive	boolean default true	When true, the iframe fills its container and respects `aspectRatio`. Set false to size with `width`/`height` only.
aspectRatio	string default "16 / 9"	CSS aspect-ratio. Only applied when `responsive: true`.
deferSrc	boolean default false	When true, the iframe is created without `src` and the SDK waits for an explicit signal to load it. Advanced use only.

Session options

Three ways to provide the session token; choose one.

Field	Type	Description
sessionToken	string \| null	A pre-fetched session JWT. The simplest option when you fetch the token before constructing the embed. The SDK will not auto-refresh unless `sessionEndpoint` or `getSessionToken` is also set.
sessionExpiresAt	string (ISO 8601) \| null	When `sessionToken` will expire. Use this together with `sessionEndpoint`/`getSessionToken` to time the auto-refresh.
sessionEndpoint	string	POST URL on your own backend that returns `{ sessionToken, expiresAt }`. The SDK calls it on mount and again before expiry. The body sent contains `{ publicKey, type, splatId }`.
sessionCredentials	"include" \| "omit" \| "same-origin" default "include"	The `credentials` option passed to `fetch(sessionEndpoint)`. Use `"include"` if your session endpoint relies on cookies for auth.
getSessionToken	({ publicKey, splatId }) => string \| { sessionToken, expiresAt? } \| Promise<...>	Custom session fetcher. Use this when `sessionEndpoint` doesn't fit (e.g. token comes from a GraphQL call). Called on mount and again before expiry.

Viewer-only options

Field	Type	Description
splatId	string \| null	The MongoDB ObjectId of the splat to display. Required for the viewer.

Editor-only options

Plan access

Moshpit.editor(...) and createEditorEmbed(...) are available on all plans.

Field	Type	Description
splatId	string \| null	Optional. If set, the editor opens this splat. If null/undefined, the editor starts in "create new" mode.

Putting it together

JavaScript

Moshpit.viewer('#moshpit-viewer', {
  publicKey: 'mpk_...',
  splatId: '65f1a2b3c4d5e6f7a8b9c0d1',
  sessionEndpoint: '/api/moshpit/viewer-session',
  responsive: true,
  aspectRatio: '16 / 9',
  borderRadius: 12,
  background: '#0a0a0a',
  loading: 'lazy',
  title: 'Living room scan',
});

JavaScript

Moshpit.editor('#moshpit-editor', {
  publicKey: 'mpk_...',
  splatId: undefined, // start a new project
  sessionEndpoint: '/api/moshpit/editor-session',
  responsive: true,
  height: '720px',
});

What's next

Viewer → SDK — concrete viewer example.
Editor → SDK — concrete editor example.
Session Tokens — when each session option is the right pick.

PostMessage Protocol