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)#

POST/library/documents/{id}/editor-session
FieldDescription
kindpdf or image; defaults from the file type.
lifetimeSeconds: 300 to 7200, default 1800.
localeThe editor language (default: the key owner’s).
Shell
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}'
201 Created
{
  "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:

EventWhenExtra fields
readyThe file is loaded.kind, version_id
savedA new version was saved.version_id
closedThe person closed the editor; the session stops working.—
errorLoading or saving failed (VERSION_CONFLICT when someone saved first).code
JavaScript (your page)
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);
});
Confirm on your server with 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

  1. No events yet.
Embedded editors · Macaaw API