> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Canvas Embed SDK

> Embed a Moda canvas inside your own product and control it from your app.

<Note>
  Canvas Embed SDK is currently available by invitation on eligible paid plans. If an API key is not enabled for embedding, session creation fails before an iframe can load.
</Note>

The Canvas Embed SDK lets you render a Moda canvas inside your own application with an iframe, then control that iframe with a versioned `postMessage` protocol.

Use it when you want to:

* Let internal users edit approved Moda canvases inside your own tool
* Let users edit a Moda canvas without opening the full Moda app
* Build your own chat, navigation, export, or save controls around the canvas
* Use Moda as the visual editing surface while your app owns the surrounding workflow

## How it works

```mermaid theme={null}
flowchart LR
  A[Your backend] -->|API key| B[Moda Public API]
  B -->|short-lived embed URL| A
  A -->|embed URL| C[Your frontend]
  C -->|iframe| D[Moda canvas embed]
  C <-->|postMessage SDK| D
```

The important split is:

| Layer                | Runs where   | What it does                                                                                                       |
| -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
| Public API           | Your backend | Lists canvases, creates embed sessions, refreshes/revokes sessions, starts exports and other server-side workflows |
| Embed iframe         | User browser | Renders the Moda canvas and handles editing, autosave, image uploads, export, and agent chat for that session      |
| Browser SDK protocol | User browser | Sends commands to the iframe and listens for events                                                                |

Your Moda API key must stay on your backend. The browser receives only a short-lived `embed_url` scoped to one canvas. The iframe exchanges that boot URL for a narrower browser credential before it loads, saves, uploads, exports, or opens chat.

## Recommended architecture

1. Your backend lists or chooses a canvas with the Moda Public API.
2. Your backend creates an embed session for that canvas.
3. Your frontend renders the returned `embed_url` in an iframe.
4. Your frontend uses `postMessage` commands to control the iframe.
5. The iframe emits events when it is ready, saves, exports, changes pages, or streams agent chat.
6. Your backend refreshes or revokes sessions when needed.

## What the SDK includes

Current beta support:

* View, edit, and view-without-export modes
* Minimal iframe chrome
* Optional secondary editing toolbar
* Optional in-iframe chat panel or external chat controlled by your app
* Real canvas rendering and editing
* Autosave and manual save
* Image insertion and image upload with a scoped embed browser credential
* PNG, JPEG, PDF, and PPTX export from the iframe
* Agent chat through the real Moda design agent for edit-mode sessions
* Session refresh and revocation

## What stays in the Public API

The browser SDK does not replace the Public API. Keep broader account and workflow operations on your backend:

* [List or search canvases](/canvas-embed/common-workflows#let-users-choose-a-canvas) (response schema documented there)
* Fetch canvas metadata or semantic design data
* Create, refresh, or revoke embed sessions
* Run server-side exports
* Start AI design tasks or remix flows
* Manage brand kits, uploads, teams, and API keys

This is intentional. It keeps your API key server-side and makes the embed flexible without turning the iframe into a proxy for every Moda endpoint.

## Current beta limitations

The beta is focused on single-user canvas embedding. These features are not included in the iframe SDK today:

* Multiplayer collaboration and live cursors
* Full Moda app chrome, team switcher, share dialogs, and billing/admin surfaces
* Customer-provisioned Moda users per end-user
* Server-side session listing or bulk revocation tools
* A stable npm package for the browser helper
* Token exchange without a query-string embed URL
* You should run a timer based on the embed session's `expires_at` to refresh ahead of it
* `load:error` carries a `code` and HTTP `status` for session/auth failures. The type 401 is distinguished by its `message`:  expired, revoked, invalid-token. Other (client-side) load failures carry `message` only

We may address some of these as the SDK matures. For now, use your own application for user access control, navigation, canvas selection, and broader workflow state.

## Next steps

Start with [Quickstart](/canvas-embed/quickstart), then read [Session API](/canvas-embed/session-api) and [Browser SDK](/canvas-embed/browser-sdk).