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
<iframe
src="https://docs.example.com/v1/open?token=ko1.…"
allow="clipboard-read; clipboard-write; fullscreen"></iframe>How it works
01- 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.
- Embed serverShow the editor
It checks the token, serves the kit’s editor page, and lets only your origins frame it.
- 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
02import { 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.mjsimport { 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-serverin the Kition SDK, open source (Apache-2.0), with a runnable example (examples/url-embed) and akition-embed-servercommand. Install it withnpm 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.