Getting Started
/
Credentials & Security
Credentials & Security
Moshpit embeds use three things to authorize a request: a public key, a secret key, and a session token. Each lives in a different place and serves a different purpose.
The three credentials
| Credential | Lives in | Lifetime | Purpose |
|---|---|---|---|
| Public key | Browser code | Until rotated | Identifies the integration; routes the iframe |
| Secret key | Server only | Until rotated | Proves the host backend can mint sessions |
| Session token | Browser (short-lived) | 15 minutes | Authenticates an iframe or API call as the integration |
How a request flows
- Your backend holds the
msk_secret. When the browser needs a session, the backend callsPOST /api/editor/embed-sessionswithAuthorization: Bearer msk_...and gets back asessionTokenJWT. - The browser receives only that JWT and the
mpk_public key. It loads the iframe athttps://moshpit.studio/{viewer|editor}/embed/{publicKey}?session={token}. - The iframe — and any API call the SDK makes from inside it — authenticates with
Authorization: Bearer {sessionToken}.
This means the secret never touches a browser. Even if the browser is fully compromised, an attacker only gets a token that expires in minutes.
Bearer beats studio cookie
If a host site embeds Moshpit and the same browser happens to have a logged-in Moshpit Studio session, the iframe sends both the embed bearer token and the studio cookie. Moshpit's auth middleware always prefers the bearer token, so the iframe is treated as the integration owner — never as the browser's logged-in studio user.
This isolation is critical: a host page that embeds your editor never gets to act on behalf of whoever happens to be browsing.
Never put the secret in browser code
The msk_ secret in front-end JavaScript, environment variables prefixed with
NEXT_PUBLIC_, or any HTML attribute can be read by anyone visiting the page.
The session-minting endpoint exists specifically so the secret stays
server-side.
What an embed CAN do
A session token authorizes the iframe to act as the integration owner — your account. That means it can:
- Read any splat owned by the integration owner.
- Save edits or publish, when the editor capability is granted.
- Call
/api/v1/splatsto list and fetch splats.
What an embed CANNOT do
- Access splats owned by other Moshpit users.
- Impersonate the browser's logged-in Moshpit account.
- Call account-level endpoints (billing, settings, integration management).
- Outlive the 15-minute JWT — without a valid session, the iframe stops responding.
Host-site domain restrictions
Each integration has a required Product name and an optional Website domain in the Integrations UI. Moshpit uses the name as the human-readable label. If supplied, the domain is normalized to a host such as app.example.com and stored as the integration's productSlug so Scenes created through the integration keep the right product boundary.
That saved domain is not a backend origin allowlist. Moshpit does not reject embed or REST requests just because their HTTP Origin is different from the saved Site domain. Anyone with a valid session token can mount the iframe. The protection model is:
- The secret stays on your backend.
- Your backend's session endpoint enforces your policies — only mint a session if the request comes from a logged-in user, comes from a specific origin, includes a valid CSRF token, etc.
- Sessions expire after 15 minutes, so a leaked token has a short blast radius.
If you want only specific host pages to be able to mint sessions, enforce that in your backend session endpoint.
What's next
- Session Tokens — the JWT shape, refresh flow, and what happens when one expires.
- Create an Integration — how to mint and rotate the key pair.