Marli Channel Partner Integration

Three things happen each time a user opens Marli:

1. The <MarliWidget> SDK in your product renders an iframe pointing at our embed URL.
2. The iframe posts a marli:ready message to your page; your page asks your backend to mint a short-lived signed JWT and posts it back as marli:bootstrap.
3. The iframe sends every chat request to our gateway with the JWT in the Authorization header. Our gateway verifies the signature, resolves the customer org, and routes to Marli.

JWTs are short-lived (5–15 minutes). When one expires, the iframe automatically asks the SDK for a fresh one — no user action required.

All of this is on your Channel Partner page in Lytica (Account → Channel Partner) as soon as your account is active. There is no welcome packet to wait for.

1. Identification

• Company name
• Technical contact name + email
• Production domain(s) (e.g. https://app.example.com)
• Staging domain(s)

Domains are the one thing we still add for you. Until yours are approved the embed is served with frame-ancestors 'self', so browsers block the iframe on every host but the Lytica test page.

2. Nothing — Your Keypair Is Generated For You

You do not send us a key. Click Generate Keypair on your Channel Partner page: we create an RS256 keypair server-side, keep the public half against your partner record, and show you the private half once. Save it to your secrets manager as CP_PARTNER_PRIVATE_JWK along with the kid shown beside it.

To rotate, generate a second keypair, deploy the new private half, then revoke the old one from the keypair table. Revoking takes effect immediately, so ship the replacement first.

3. Identifier Conventions

• partnerOrgId: stable customer/account ID in your system (e.g. publisher_12345). Must not change.
• userId: stable user ID (e.g. user_789). Must not change. Only needs to be unique within one partnerOrgId.

Your backend mints a JWT for each user session. Mint a fresh one when:

• The page first loads.
• The iframe posts marli:expired back to your page (the SDK handles this).

Header

Payload (exactly five claims — additional claims are ignored)

// Header
{ "alg": "RS256", "kid": "partner-key-2026-05-06" }

// Payload
{
  "iss": "iscream",
  "iat": 1778101494,
  "exp": 1778101794,
  "partnerOrgId": "publisher_12345",
  "userId": "user_789"
}

We deliberately do not ask you to put email, name, role, permissions, or PII in the JWT. The smaller the surface, the smaller the leak risk.

Identity-Bearing Claim Format — No Colons

partnerOrgId and userId must not contain the colon character (:). Internally we namespace end users as cp:<slug>:<partnerOrgId>:<userId>. Colons in either claim would create ambiguous internal IDs.

A JWT with a colon in either claim is rejected at the gateway with HTTP 400 PARTNER_JWT_MISSING_CLAIMS.

If your IDs use colons, two clean encodings:

• Replace : with _ — keep it deterministic.
• URL-encode — team%3A1%3Amember%3A2. Reversible.

Your backend exposes one endpoint (e.g. POST /api/marli-token) that the SDK calls from the partner-side page. The recommended path uses our createMarliMintHandler helper:

import { createMarliMintHandler } from '@lyticalabs/marli-sdk/server';

export const POST = createMarliMintHandler({
  partnerSlug: process.env.CP_PARTNER_SLUG!,
  privateJwkJson: process.env.CP_PARTNER_PRIVATE_JWK!,
  kid: process.env.CP_PARTNER_KID!,
  alg: 'RS256',
  resolveContext: async (request) => {
    const session = await getYourSession(request);
    if (!session) return null;
    return {
      partnerOrgId: session.activeOrg.id,
      userId: session.user.id,
    };
  },
});

export const runtime = 'nodejs';

The helper handles JWT composition, key import + caching, claim-format validation, TTL clamping, and sanitized error envelopes.

Required env vars:

CP_PARTNER_SLUG=iscream
CP_PARTNER_KID=partner-key-2026-05-06
CP_PARTNER_PRIVATE_JWK={"kty":"RSA","d":"…","n":"…",…}

Install the SDK (during pilot, LyticaLabs provides a tarball; npm publish is on the Phase 2 roadmap):

npm install @lyticalabs/marli-sdk

Mount it in any client component:

'use client';
import { MarliWidget } from '@lyticalabs/marli-sdk/react';

export function MarliPanel() {
  return (
    <MarliWidget
      baseUrl="https://alpha.lyticalabs.ai"
      partnerSlug="iscream"
      onMintJwt={async () => {
        const res = await fetch('/api/marli-token', { method: 'POST' });
        if (!res.ok) throw new Error('mint failed');
        const { jwt } = await res.json();
        return jwt;
      }}
      iframeAttrs={{
        title: 'Marli',
        allow: 'clipboard-read; clipboard-write',
        style: { width: '100%', height: '600px', border: 'none' },
      }}
      onError={(err) => {
        console.error('[marli]', err.code, err.message);
      }}
    />
  );
}

The SDK enforces three security invariants automatically: it rejects invalid baseUrls at construction, locks the iframe sandbox to a known-safe value, and only sends JWTs to the canonical origin.

Optional. A customer org is created the first time you mint a JWT carrying its partnerOrgId, so nothing has to be registered ahead of the first chat. Call this when you want the row to exist earlier — with a display name of your choosing — typically from your own customer-creation flow:

curl -X POST https://alpha.lyticalabs.ai/api/v1/cp/orgs \
  -H "Authorization: Bearer ${CP_PARTNER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerExternalOrgId": "publisher_12345",
    "name": "Acme Media"
  }'

Idempotent — calling twice returns 409 PARTNER_ORG_PROVISION_DUPLICATE (row already exists).

SDK-Level (Parent Page) — Your onError Handler

Gateway-Level (Inside the Iframe)

If your product uses a Content Security Policy, allow-list our domain as a frame source:

Content-Security-Policy: frame-src https://alpha.lyticalabs.ai

We enforce the reciprocal allow-list: the iframe only loads if your domain is in the allowedDomains we registered. Iframes from unlisted origins are blocked at the browser before any content paints.

Chat History Is Session-Only

The iframe holds in-memory conversation context via the AI SDK's useChat hook. It is not persisted server-side. Page reload or tab close clears the conversation. Cross-session history is on the Phase 2 roadmap.

Single Embed Host (No Separate Staging Surface)

The same embed URL serves staging and production. To separate usage, use different partnerOrgId values per environment.

Tool-Call Rendering Is Text-Only

If Marli uses a tool that produces structured output (charts, citations), the iframe currently renders only the text portion. Rich rendering is queued for a near-term release.

• Passwords, hashes, secrets, API keys
• Personally-identifying data without consent
• Customer business data (revenue, account values, customer lists)
• Long-lived tokens of any kind (TTL >1 hour)

The JWT is a session pass — keep it minimal. Usage is attributed by (partnerOrgId, userId).

Use this path if you're on a non-Node/Next.js stack, want custom claim mapping, or need to inspect every JWT before signing. For everyone else, the helper-based default is shorter, safer, and stays in sync with verifier changes automatically.

import { importJWK, type JWK, SignJWT } from 'jose';
import { NextResponse } from 'next/server';

export const runtime = 'nodejs';
export const dynamic = 'force-dynamic';

export async function POST(request: Request) {
  const session = await getYourSession(request);
  if (!session) {
    return NextResponse.json({ error: 'unauthenticated' }, { status: 401 });
  }

  const { id: userId } = session.user;
  const { id: partnerOrgId } = session.activeOrg;

  // Validate no colons in identity-bearing claims
  if (
    typeof partnerOrgId !== 'string' || partnerOrgId.length === 0 ||
    partnerOrgId.includes(':') ||
    typeof userId !== 'string' || userId.length === 0 ||
    userId.includes(':')
  ) {
    console.error('[marli-token] invalid claims');
    return NextResponse.json({ error: 'mint_failed' }, { status: 500 });
  }

  try {
    const privateJwk = JSON.parse(process.env.CP_PARTNER_PRIVATE_JWK!) as JWK;
    const kid = process.env.CP_PARTNER_KID!;
    const alg = process.env.CP_PARTNER_ALG ?? 'RS256';
    const slug = process.env.CP_PARTNER_SLUG!;

    const privateKey = await importJWK(privateJwk, alg);
    const now = Math.floor(Date.now() / 1000);

    const jwt = await new SignJWT({ partnerOrgId, userId })
      .setProtectedHeader({ alg, kid })
      .setIssuer(slug)
      .setIssuedAt(now)
      .setExpirationTime(now + 300)
      .sign(privateKey);

    return NextResponse.json({ jwt });
  } catch (err) {
    console.error('[marli-token] mint failed:', err);
    return NextResponse.json({ error: 'mint_failed' }, { status: 500 });
  }
}

What you give up by writing this by hand:

• Forward compatibility — the helper updates with the SDK when new claim-format invariants are added.
• Key caching — the helper imports the JWK once and caches it.
• TTL clamping — the helper clamps to [60, 900] seconds.
• Sanitized error envelope — guaranteed no leakage of error details to the browser.

• Technical questions during integration: your assigned LyticaLabs technical contact.
• Production incidents: the emergency contact in your partner agreement.
• Code-level reference: the apps/cp-test directory contains a complete worked-example partner integration.