Embedding Kelynto

Kelynto developer documentation. Sandbox access: marc@kelynto.com.

Show a client's Kelynto views inside your own application: the weekly review, the Outlook, the causes each review raised with their evidence, and This quarter. Your server asks Kelynto for an embed token for one person and one client; your page puts the address it gets in an iframe. The person reads that client's views in your page, under your brand, without a Kelynto account and without leaving your application. The same client workspace stays a standalone Kelynto workspace for the client's own people.

What you need

  • A partner key with the scope embed:create. It is never given unless asked for: ask for it when you make the key in the partner console, or ask whoever operates Kelynto for you.
  • Your embed origins: the origins of the pages that will frame Kelynto, such as https://planning.example.com. Whoever operates Kelynto for you records them on your partner record. Each is a scheme, a host and an optional port, served over https. Only a page on one of them can show an embedded view.
  • Optionally, the abilities your people may have beyond reading: comment (leave a dated context note on a store) and edit (edit the commentary of a review that is not published yet, and read drafts). Without them, a person reads the client's published reviews, the Outlook and This quarter.

Quickstart

1. Mint a token on your server, for each page load

The token names one client, one person of yours (the id your application gives them, and their name), the origin of your page, and the view to open on. It lasts five minutes unless you ask for less (30 seconds) or more (ten minutes at most), and it can be exchanged once. Keep the partner key on your server; a token is the only thing your page sees.

Python:

import os
import requests  # pip install requests

KELYNTO_URL = os.environ["KELYNTO_URL"]            # for example https://app.example.com
PARTNER_KEY = os.environ["KELYNTO_PARTNER_KEY"]     # kpk_..., with the scope embed:create


def embed_url(client: str, user_id: str, user_name: str, view: str = "review") -> str:
    r = requests.post(
        f"{KELYNTO_URL}/api/partner/v1/clients/{client}/embed/tokens",
        headers={"Authorization": f"Bearer {PARTNER_KEY}"},
        json={"user": {"id": user_id, "name": user_name}, "origin": "https://planning.example.com",
              "view": view, "mode": "header"},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["url"]

Node (18 or later, with the built-in fetch):

const KELYNTO_URL = process.env.KELYNTO_URL;          // for example https://app.example.com
const PARTNER_KEY = process.env.KELYNTO_PARTNER_KEY;  // kpk_..., with the scope embed:create

export async function embedUrl(client, userId, userName, view = 'review') {
  const r = await fetch(`${KELYNTO_URL}/api/partner/v1/clients/${encodeURIComponent(client)}/embed/tokens`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${PARTNER_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      user: { id: userId, name: userName },
      origin: 'https://planning.example.com',
      view,
      mode: 'header',
    }),
  });
  if (!r.ok) throw new Error(`Kelynto refused the token: ${r.status} ${r.headers.get('X-Error-Code')}`);
  return (await r.json()).url;
}

The answer:

{
  "token": "eyJ...",
  "url": "https://app.example.com/embed/start?token=eyJ...",
  "expires_at": "2026-11-04T15:05:00Z",
  "origin": "https://planning.example.com",
  "mode": "header",
  "view": "review",
  "views": ["review", "outlook", "findings", "quarter"],
  "abilities": [],
  "token_id": "4c1f..."
}

The request takes these fields:

FieldWhat it is
user.idThe id your application gives the person, 1 to 128 letters, digits and . _ : @ + -. It is what the client's audit log names.
user.nameThe person's name, shown beside a note or an edit they make. Optional.
originThe origin of the page that frames Kelynto: one of your embed origins.
viewThe view the frame opens on: review, outlook, findings or quarter.
viewsThe views the session may open. All four unless you list fewer.
abilitiescomment, edit, both or none, within what your partner record allows.
modeHow the session travels: cookie (the default) or header. See Cookie or header.
ttl_secondsHow long the token may wait to be exchanged: 30 to 600, 300 by default.
weekThe week the review opens on, as its first day. The latest when left out.

2. Put the address in an iframe

A minimal page, served from your embed origin:

<!doctype html>
<html lang="en">
  <head><meta charset="utf-8"><title>Weekly review</title></head>
  <body>
    <iframe id="kelynto" title="Weekly review" src="{{ embed_url }}"
            style="width: 100%; border: 0; min-height: 480px" referrerpolicy="origin"></iframe>
    <script>
      const KELYNTO = 'https://app.example.com';   // the origin of the address you were given
      const frame = document.getElementById('kelynto');
      window.addEventListener('message', (event) => {
        if (event.origin !== KELYNTO || event.source !== frame.contentWindow) return;
        const m = event.data || {};
        if (m.source !== 'kelynto') return;
        if (m.type === 'resize') frame.style.height = m.height + 'px';
        if (m.type === 'session-ended') location.reload();   // mint a new token and open again
      });
    </script>
  </body>
</html>

{{ embed_url }} is the url your server got in step 1, written into the page by your template. Mint a new one for every page load: a token works once. referrerpolicy="origin" lets browsers that do not report the framing page any other way tell Kelynto your page's origin.

3. Try it with the sandbox

The sandbox partner is set up to embed: its embed origin is http://localhost:8472, both abilities are allowed, and it carries a synthetic brand. Serve the minimal page above from that origin on your own machine, mint a token for each page load with your sandbox key, and open http://localhost:8472/. Ask for another origin with your sandbox request if you test from a hosted page. Every client, person and figure in the sandbox is synthetic. (Kelynto also has a mock partner application that does the same with a choice of client, person, view and mode: ask to see it in a call.)

What a person sees

  • Weekly review: the client's review as its document, the same one the Word, PDF and PowerPoint files and the emails are made from, with a choice of week. A reader sees published reviews; with edit, drafts too, with the commentary to edit.
  • Causes: what each review raised, by part of the review, with the records on file for each.
  • Outlook: the weeks ahead by cause, against the client's plan or forecast, each item with its range and basis.
  • This quarter: the period's reviews and decisions, and what followed.

Every figure is the one the client's own people read in Kelynto, from the same code, and each answer carries where it came from (the run of the review it is read from). With comment, a person can leave a dated note on a store from the weekly review, when the client has store notes switched on. A note carries no amount and changes no figure; it is shown with the person's name and your company's.

Cookie or header

The token is exchanged once for a short session (30 minutes unless your partner record says otherwise, five to 240). The session travels one of two ways, chosen when you mint the token:

cookieheader
Where the session isAn HttpOnly cookie, SameSite=None; Secure; Partitioned, sent only to Kelynto's embed routesIn the page's memory, sent in a header on each request
A script in the page can read itNoYes, while the page is open
Works when the browser blocks cookies of a site framed in another siteNoYes
A reload of the frameKeeps the session until it expiresNeeds a new token: the page tells yours session-ended

cookie keeps the session out of reach of any script. Browsers that keep partitioned cookies (cookies of a framed site, kept for the site that frames it only) accept it; a browser that blocks every cookie of a framed site does not, and the page then tells yours {"type": "error", "code": "cookies_blocked"}. Mint a header token and open the frame again when you receive it. header works in every browser, and needs a new token on every reload. If your people use browsers that block cookies of framed sites, mint header tokens from the start.

Messages between the frame and your page

The frame posts messages to your page's origin only, never to any other, each with source: "kelynto":

MessageWhen
{"type": "ready", "view": "review"}The session is open and the first view is shown.
{"type": "resize", "height": 1240}The content's height changed, in CSS pixels. Set the iframe's height to it.
{"type": "navigate", "view": "outlook", "week": "2026-10-19"}The person moved to another view or week.
{"type": "session-ended"}The session ended, or the link was used already. Mint a new token.
{"type": "error", "code": "cookies_blocked"}The browser kept no cookie. Mint a header token.

Your page can send one message to the frame, to Kelynto's origin, to move it:

frame.contentWindow.postMessage({ source: 'partner', type: 'navigate', view: 'quarter' }, KELYNTO);

The frame reads a message only from your origin and from the window that frames it, and only in that shape. Check event.origin and event.source the same way on your side, as the page above does.

Ending sessions

A session ends when it expires, when your page's person signs out (call DELETE /api/partner/v1/clients/{client}/embed/sessions?user=<id>, or leave out user to end every session of the client), when the key that minted its token is revoked or expires, when your partner record is suspended, or when its origin is taken off your embed origins. Each takes effect on the session's next request.

Branding

Once whoever operates Kelynto for you records your brand name, the embedded views carry your name, your logo and your primary colour in the frame's header, with "Powered by Kelynto" unless you chose to leave it out. The same brand goes on what Kelynto delivers for your clients: the review as Word, PDF and PowerPoint, the emails a review is sent with and the Monday pack print your name and logo where "Prepared with Kelynto" was, and a client that kept the default document template takes your primary colour. A colour a client chose for its own documents stays theirs. A logo is a PNG or JPEG file you send to whoever operates Kelynto; Kelynto stores it re-encoded and never fetches it from your site.

Mail from your name and your domain

The mail Kelynto sends for your clients (a review sent, the Monday pack) can carry your name as its sender name. The sending address stays Kelynto's until your domain is verified and set up for sending:

  1. Whoever operates Kelynto adds your domain; you are given a TXT record such as _kelynto-sender.planning.example.com with the value kelynto-sender-verification=<value>.
  2. You publish it in your DNS. Kelynto reads it (a DNS lookup) and marks the domain verified. Kelynto never changes your DNS.
  3. The mail service that sends for the deployment is set up to send for your domain (the records it asks for, such as SPF and DKIM, are published in your DNS), and the operator then turns sending from your domain on. From then on the mail for your clients comes from an address of your domain, such as reviews@planning.example.com.

Security in short

  • A token is signed by Kelynto, lasts minutes, is bound to one client, one person and one of your origins, and works once. A second use is refused and recorded in the client's audit log.
  • Before serving an embed page, Kelynto's web server sets Content-Security-Policy: frame-ancestors to the one origin the page's token was minted for. Every other page of Kelynto keeps frame-ancestors 'none' and X-Frame-Options: DENY, so it cannot be framed by anyone.
  • An embedded session reads one client workspace, through the same code and the same row-level security as the client's own people, holds only the abilities your partner record allows, and opens no other part of Kelynto.
  • The token minted, the session started and ended, each review read, each note and each edit are in the client's audit log, with your person and your company named.