Syntheia DOCX Compare Embed Integration Kit

Embed the Syntheia DOCX Compare experience directly inside your application via an <iframe>, authenticated with an API key instead of an interactive login. Your users upload two DOCX files, run a comparison, and review/export the redline, all without ever seeing a Syntheia login screen or subscription prompt, and without being logged out mid-session.

This kit contains:

• This guide: how the integration works and how to wire it up.
• example/: a tiny, zero-dependency reference implementation (a backend that mints embed tokens plus a demo embedding page) you can run and read.

---

How it works

The API key is a long-lived secret that must stay on your server. Your backend exchanges it for a short-lived, workspace-scoped embed token, and only that token reaches the browser.

your page  → your backend  →(x-user-api-key: syn_…)→  POST /auth/embed/token  → { token, expiresIn }
your page  ← token
your page  → <iframe …/docx-compare?iframe=true>  +  postMessage({ type:'INIT_EMBED', accessToken: token })
iframe     → DOCX Compare runs (Bearer embed token, scoped to DOCX Compare only)   ✓

The embed token can only reach the DOCX Compare endpoints in your one workspace; it cannot access the rest of the Syntheia platform or any other tenant.

---

What Syntheia provides you

Item	Value
API key (secret)	syn_prd_…, delivered separately over a secure channel. Never commit it or send it to the browser.
Workspace ID	a numeric id, provided by Syntheia
API base URL	https://api.us.supercomparer.com
App base URL	https://app.us.supercomparer.com
Origin allowlist	Send us the origin(s) you'll embed from (e.g. https://app.example.com) so we add them to the iframe's CSP (see step 3).

---

Integration

1. Backend: exchange your API key for an embed token

Add a small server-side endpoint that calls Syntheia and returns the token to your page. The key stays server-side.

POST https://api.us.supercomparer.com/auth/embed/token
Header: x-user-api-key: syn_prd_…
→ 200 { "token": "<JWT>", "expiresIn": "7d" }

// e.g. GET /session on your backend
const r = await fetch('https://api.us.supercomparer.com/auth/embed/token', {
  method: 'POST',
  headers: { 'x-user-api-key': process.env.SYN_API_KEY },
});
return await r.json(); // { token, expiresIn }

See example/server.js for the complete version.

2. Frontend: embed the iframe and hand it the token

Point the iframe at DOCX Compare in embed mode (?iframe=true hides all Syntheia portal chrome), then deliver the token with postMessage.

const APP = 'https://app.us.supercomparer.com';
const WORKSPACE_ID = '<your workspace id>';
const { token } = await (await fetch('/session')).json();

frame.src = `${APP}/workspace/${WORKSPACE_ID}/docx-compare?iframe=true`;
// The app's message listener can mount slightly after the iframe loads, so resend until it sticks.
const send = () => frame.contentWindow.postMessage({ type: 'INIT_EMBED', accessToken: token }, APP);
const t = setInterval(send, 500); setTimeout(() => clearInterval(t), 20000); send();

The token is long-lived (7-day) and applied in place, so re-minting on page load (and on tab focus, as a safety net) keeps the session alive indefinitely with no refresh protocol and no lost work. See example/index.html.

3. Allowlist your embedding origin

For the browser to render the iframe, the origin of the page doing the embedding must be listed in Syntheia's Content-Security-Policy frame-ancestors. Send us every origin you'll embed from (scheme + host, e.g. https://app.example.com) and we'll allowlist it. Until an origin is added, the browser blocks the frame.

---

Run the example

cd example
cp .env.example .env          # Syntheia endpoints are pre-filled
#   → set SYN_API_KEY and WORKSPACE_ID to the values Syntheia gave you
set -a && . ./.env && set +a
node server.js                # Node 18+
# open http://localhost:4500

http://localhost:4500 is already on the allowlist, so the demo renders out of the box.

Backend-only smoke test (no browser/CSP needed) that confirms the key works end to end:

TOKEN=$(curl -s -XPOST https://api.us.supercomparer.com/auth/embed/token \
  -H "x-user-api-key: $SYN_API_KEY" | grep -oP '"token":"\K[^"]+')
curl -s -o redline.docx -w '%{http_code}\n' -XPOST https://api.us.supercomparer.com/reports/instant \
  -H "Authorization: Bearer $TOKEN" -H "x-app-name: PORTAL" \
  -F "benchmarkDocument=@original.docx" -F "targetDocument=@revised.docx"

---

Security notes

• The API key never leaves your backend. The browser only ever sees the short-lived embed token.
• Least privilege. The embed token is scoped to a single workspace and can only reach the DOCX Compare endpoints, not the rest of the platform, and not other tenants.
• postMessage targets the Syntheia app origin explicitly (https://app.us.supercomparer.com), never '*'. Keep it that way.
• Revocation. Ask Syntheia to revoke the key and no new sessions can be minted; any already-issued token simply expires on its own (7-day TTL).