Guides
Embedded editors
Show the Macaaw PDF and picture editors inside your own site with short-lived editor sessions, and try them in the demo.
Show the Macaaw PDF editor (rotate, remove and reorder pages) or picture editor (rotate, flip, scale down) inside your own site, for one document of your workspace library. Like embedded signing, your server asks for a short-lived editor session and your page opens its URL in an iframe. Saving makes a new version; nothing is ever overwritten.
1. Allow your site#
Add your site's origin under Account → Developer → Settings → Allowed embed origins. The editor page sends Content-Security-Policy: frame-ancestors with exactly those origins (and this site, for the demo below), so browsers refuse to frame it anywhere else.
2. Create a session (on your server)#
| Field | Description |
|---|---|
kind | pdf or image; defaults from the file type. |
lifetime | Seconds: 300 to 7200, default 1800. |
locale | The editor language (default: the key owner’s). |
curl https://macaaw.com/public/v1/library/documents/$DOC_ID/editor-session \
-H "Authorization: API-Key $MACAAW_API_KEY" \
-H "Content-Type: application/json" -d '{"lifetime": 900}'{
"id": "3c5d…",
"kind": "pdf",
"url": "https://macaaw.com/e/Yk3…",
"expires_at": "2026-11-14T13:45:00.000000Z",
"base_version_id": "4",
"events": [
"ready",
"saved",
"closed",
"error"
]
}The key needs the editor-sessions scope. The URL is the credential: treat it like a password and create a new one each time.
3. Listen for events#
The editor posts { type: "macaaw.editor", event, session, … } to the parent window, only to your allowed origins:
| Event | When | Extra fields |
|---|---|---|
ready | The file is loaded. | kind, version_id |
saved | A new version was saved. | version_id |
closed | The person closed the editor; the session stops working. | — |
error | Loading or saving failed (VERSION_CONFLICT when someone saved first). | code |
window.addEventListener('message', (e) => {
if (e.origin !== 'https://macaaw.com' || e.data?.type !== 'macaaw.editor') return;
if (e.data.event === 'saved') refreshVersion(e.data.version_id);
});GET /library/documents/{id}/versions: messages are a convenience for your interface.Demo#
Create a session with your key (sandbox keys work), paste its URL here and watch the events. The demo frames only editor URLs of this site and shows only messages from it.
Events
- No events yet.