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.

When your account is ready you receive a "welcome packet":

1. Identification

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

2. A Public JWK (JSON Web Key)

Generate an RS256 (RSA 2048-bit) or ES256 (P-256 ECDSA) keypair. Keep the private half in your secrets manager; send LyticaLabs the public half as a JWK.

import { generateKeyPair, exportJWK } from 'jose';

const { publicKey, privateKey } = await generateKeyPair('RS256', {
  modulusLength: 2048,
  extractable: true,
});
const publicJwk = await exportJWK(publicKey);
const privateJwk = await exportJWK(privateKey);

const kid = `partner-key-${new Date().toISOString().slice(0, 10)}`;

console.log('Send this to LyticaLabs:');
console.log(JSON.stringify({ kid, alg: 'RS256', publicJwk }, null, 2));

console.log('Save these in your secrets manager (NEVER commit):');
console.log('CP_PARTNER_PRIVATE_JWK=' + JSON.stringify(privateJwk));
console.log('CP_PARTNER_KID=' + kid);

openssl genrsa -out partner-private.pem 2048
openssl rsa -in partner-private.pem -pubout -out partner-public.pem
# convert to JWK with jose's importKey + exportJWK

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.

Before any user from a given customer can use Marli, register that customer. This is a one-time server-to-server call (typically during your 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 welcome packet.
• Code-level reference: the apps/cp-test directory contains a complete worked-example partner integration.