Embed · By link · @kition/embed-server

Embed by link: one iframe

Embed by link: run the embed server on your server, then frame one signed iframe link. Your server signs a link for one person and one file; the embed server shows the kit’s editor and reads and saves the file through signed callbacks to your storage. It keeps no document. Single-user embedding by link is free and needs no key.

Copy for AI
your page · from docs/sdk/url.md
<iframe
  src="https://docs.example.com/v1/open?token=ko1.…"
  allow="clipboard-read; clipboard-write; fullscreen"></iframe>
Way 1 · @kition/embedPrefer to mount it in your page? Co-editing, your agent in the open document and draft review come with @kition/embed in your page; embedded by link, the editor is single-user.

How it works

01
  1. Your serverMint the link

    Sign an open token for the person and the file with your Ed25519 key, with edit, comment or view from your own permissions.

  2. Embed serverShow the editor

    It checks the token, serves the kit’s editor page, and lets only your origins frame it.

  3. Your callbacksHEAD, GET, PUT /files/{file}

    Every request is HMAC-signed. A save carries the version it read (If-Match), so a stale tab never writes over a newer file.

Run it

02
embed-server.mjs · from packages/embed-server/README.md
import { startEmbedServer } from '@kition/embed-server'

const service = await startEmbedServer({
  id: 'docs-example',                     // the `aud` your open tokens name
  secret: process.env.DOC_SESSION_SECRET!, // at least 32 characters, signs the page's sessions
  integrators: [{
    iss: 'acme.app',                       // the `iss` your open tokens name
    keys: [{ kid: 'acme-1', publicKey: '<base64url Ed25519>', tenant: 'acme', iss: 'acme.app' }],
    callbackUrl: 'https://app.acme.com/kition',
    secret: process.env.ACME_CALLBACK_SECRET!, // shared with your server; signs every callback
    origins: ['https://app.acme.com'],     // who may frame the editor
  }],
  kits: [{ id: 'kit.note', path: 'note-ui/', extensions: ['.md'] }], // one entry per kit package you serve
  kitsUrl: 'https://cdn.example.com/kition/', // the kit packages: static files on your CDN (or kitsDir and kitsPort)
  host: '0.0.0.0',                         // default 127.0.0.1
  port: 8080,
})
console.log(service.url)

// or, from a config file with those options:
// npx @kition/embed-server ./embed-server.config.mjs
your server · from docs/sdk/url.md
import { signOpenToken } from '@kition/sync/openToken'

const token = await signOpenToken({
  iss: 'acme.app', aud: 'docs-example', tenant: 'acme',
  sub: user.id, name: user.name,
  file: 'res-42',            // your immutable file id
  version: 'v7',             // the version you open
  doc_key: 'res-42.g3',      // the file's generation: change it when the file is replaced
  perms: { edit: true, comment: true, download: true, share: false, export: true },
  watermark: null,           // or { text: 'Ann · Confidential' }
  iat: now, exp: now + 300,  // at most an hour; a few minutes is enough
}, 'acme-1', privateKey)
const src = `https://docs.example.com/v1/open?token=${encodeURIComponent(token)}`

Your server answers HEAD, GET and PUT /files/{file} under callbackUrl and checks each request with verifyCallback from @kition/embed-server/callbacks. The embed-by-link guide

What to know

03
  • Single-user: one editor per link. Real-time co-editing goes through Kition Server with the editor embedded in your page.
  • You run the embed server; there is no hosted one. It is @kition/embed-server in the Kition SDK, open source (Apache-2.0), with a runnable example (examples/url-embed) and a kition-embed-server command. Install it with npm i @kition/embed-server.
  • It opens files your storage already has: no new files, and no exports to new files.
  • It serves the kit packages you give it. Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet.