---
title: "Embed by link — a Kition editor in one signed iframe, with @kition/embed-server"
description: "The second way to embed a Kition editor: run the embed server (@kition/embed-server) and frame one signed link, with no module in your page. The file is read and saved through signed callbacks to your own storage. Single-user, free, no key."
canonical: "https://developer.kition.ai/url"
---

> Canonical HTML: [https://developer.kition.ai/url](https://developer.kition.ai/url)

[Embed](https://developer.kition.ai/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.

by link · weekly-team-sync.md

Run the same by-link setup on your machine: node examples/url-embed/serve.mjs in kition-sdk starts an integrator page, the embed server and the kit packages.

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/embed**Prefer 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.](https://developer.kition.ai/embed#in-your-page)

## How it works

01

1.  Your server**Mint 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 server**Show the editor**
    
    It checks the token, serves the kit’s editor page, and lets only your origins frame it.
    
3.  Your callbacks**HEAD, 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](https://developer.kition.ai/docs/url)

## What to know

03

-   Single-user: one editor per link. Real-time co-editing goes through [Kition Server](https://developer.kition.ai/collaboration) 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.

[Embed in your page](https://developer.kition.ai/embed#in-your-page)[Open playground](https://developer.kition.ai/playground)
