Authenticated Experiences

When to use

Authenticated experiences are for apps that need:

• Private or non-public experiences
• Per-user session context (userId)
• Server-side control over session creation
• Custom integration overrides (return URL, close button)

Flow

Your backend  →  POST /v1/sessions  →  Session Manifest
                                              ↓
Your frontend  ←  manifest or sessionEndpoint  ←  SDK

1. Mint on your server

Call the Liforma API with your developer API key. Never expose the key to the browser.

curl -X POST https://api.liforma.ai/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"experienceId": "exp_01DEMO1SPANISHCAFE"}'

2. Pass to the client

Recommended: use a same-origin sessionEndpoint so credentials never touch SSR HTML.

<LiformaExperience
  experienceId="exp_01DEMO1SPANISHCAFE"
  sessionEndpoint="/api/liforma-session"
/>

3. Implement sessionEndpoint

// app/api/liforma-session/+server.ts
import { json } from '@sveltejs/kit';

export async function POST({ request }) {
  const { experienceId, userId } = await request.json();

  const res = await fetch('https://api.liforma.ai/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LIFORMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ experienceId, userId })
  });

  if (!res.ok) {
    return json({ message: 'Failed to mint session' }, { status: res.status });
  }

  return json(await res.json());
}

Contract: POST { experienceId, userId? } → Session Manifest

SSR warning

Do not pass credential-bearing manifests through server load functions. The sessionToken in the manifest would be embedded in HTML. Use sessionEndpoint or client-side minting instead.

API key

Obtain a developer API key from the Liforma dashboard. Store it in server environment variables only.