Per-user door

On the per-user door, each answer is filtered on one customer. Your server says which customer is logged in, with your API key. Concatflow returns a short-lived token. Your page gives that token to the assistant, which receives it by postMessage.

Before you start

In the assistant’s dashboard:

Isolation is signed. It defines the partition keys, such as customer_id.
In Doors, the per-user door is on, and Allowed origins lists your app’s origin.
The assistant is published.

You also need an API key and the assistant ID.

1. Install the server SDK

npm install @concatflow/node

@concatflow/node has no dependencies and needs Node 18 or later.

2. Add a session route

Add one route that opens a session for the logged-in customer. The page calls it on load, and again when the token expires.

Take the partition from your own session, never from the request. req.body.customerId is whatever the visitor typed in their console. req.user.customerId, set by your login, is the truth.

Express
Next.js (App Router)

server.ts

import express from "express";
import { Concatflow, ConcatflowError } from "@concatflow/node";
import { requireLogin } from "./auth"; // your middleware, sets req.user

const app = express();
const concatflow = new Concatflow({ apiKey: process.env.CONCATFLOW_API_KEY! });

app.post("/api/concatflow/session", requireLogin, async (req, res) => {
  try {
    const session = await concatflow.sessions.create({
      assistantId: process.env.CONCATFLOW_ASSISTANT_ID!,
      partitions: { customer_id: req.user.customerId },
    });
    res.json(session); // { token, expiresAt }
  } catch (err) {
    if (!(err instanceof ConcatflowError)) throw err;
    console.error(err.status, err.code);
    res.status(502).json({ error: err.code ?? "concatflow_error" });
  }
});

app.listen(3000);

lib/concatflow.ts

import "server-only";
import { Concatflow } from "@concatflow/node";

const concatflow = new Concatflow({ apiKey: process.env.CONCATFLOW_API_KEY! });

export function openSession(customerId: string) {
  return concatflow.sessions.create({
    assistantId: process.env.CONCATFLOW_ASSISTANT_ID!,
    partitions: { customer_id: customerId },
  });
}

app/api/concatflow/session/route.ts

import { auth } from "@/lib/auth"; // your auth
import { openSession } from "@/lib/concatflow";

export async function POST() {
  const user = await auth();
  if (!user) return new Response(null, { status: 401 });
  return Response.json(await openSession(user.customerId));
}

The keys of partitions must be exactly the partition keys of the assistant’s isolation. A missing or extra key fails with 403 partition_keys_mismatch. Values are strings or numbers.

3. Show the assistant

Script tag
npm
Next.js

index.html

<script src="https://app.concatflow.com/widget.js"></script>
<div id="assistant"></div>
<script>
  async function openSession() {
    const res = await fetch("/api/concatflow/session", { method: "POST" });
    if (!res.ok) throw new Error("Could not open a Concatflow session");
    return (await res.json()).token;
  }

  openSession().then((token) => {
    Concatflow.init({
      session: token,
      launcher: "bar",
      target: "#assistant",
      onSessionExpired: openSession,
    });
  });
</script>

assistant.ts

import { loadConcatflow } from "@concatflow/embed";

async function openSession(): Promise<string> {
  const res = await fetch("/api/concatflow/session", { method: "POST" });
  if (!res.ok) throw new Error("Could not open a Concatflow session");
  return (await res.json()).token;
}

const Concatflow = await loadConcatflow();
export const assistant = Concatflow.init({
  session: await openSession(),
  launcher: "bar",
  target: "#assistant",
  onSessionExpired: openSession,
});

The server component opens the first session. The client component renews it.

app/dashboard/page.tsx

import { Suspense } from "react";
import { redirect } from "next/navigation";
import { auth } from "@/lib/auth";
import { openSession } from "@/lib/concatflow";
import { Assistant } from "./assistant";

export default function Page() {
  return (
    <Suspense>
      <Dashboard />
    </Suspense>
  );
}

async function Dashboard() {
  const user = await auth();
  if (!user) redirect("/login");
  const { token } = await openSession(user.customerId);
  return <Assistant customerId={user.customerId} initialToken={token} />;
}

<Suspense> is required when Cache Components are on, as in a new Next.js 16 app: auth() reads the request.

app/dashboard/assistant.tsx

"use client";
import { ConcatflowAssistant } from "@concatflow/embed/react";

async function renew(): Promise<string> {
  const res = await fetch("/api/concatflow/session", { method: "POST" });
  if (!res.ok) throw new Error("Could not open a Concatflow session");
  return (await res.json()).token;
}

export function Assistant({ customerId, initialToken }: { customerId: string; initialToken: string }) {
  return (
    <ConcatflowAssistant
      key={customerId}
      session={initialToken}
      launcher="bubble"
      onSessionExpired={renew}
    />
  );
}

That’s all. Each customer now sees answers on their own rows only. For a complete app with a login, renewal and an isolation check, follow the Next.js tutorial.

What the token is

Opaque. It describes nothing. The partition stays on Concatflow’s side.
Short-lived. It expires 15 minutes after it was opened. onSessionExpired renews it without the customer noticing. See Session renewal.
Never in a URL. The page hands it to the iframe by postMessage, so it stays out of logs and Referer headers.
Stored hashed. Concatflow keeps a SHA-256 of the token, never the token.

The conversation outlives tokens. There is one conversation per assistant and per partition. When the customer comes back tomorrow, the assistant shows their last 50 questions.

When the customer changes

When a customer logs out, call destroy(). When another customer logs in on the same page, destroy() the assistant and init() a new one with the new customer’s token.

Use setSession() only to renew the same customer’s token. The iframe loads a conversation’s history once: a token for another customer would leave the previous customer’s questions on screen. In React, give the component a key per customer, as above, so it remounts.

Several partition keys

If the isolation signs two keys, send both:

await concatflow.sessions.create({
  assistantId: process.env.CONCATFLOW_ASSISTANT_ID!,
  partitions: { customer_id: user.customerId, region: user.region },
});

Errors

sessions.create throws a ConcatflowError on any non-2xx answer. The ones you will meet first:

Status	Code	Fix
401	`invalid_api_key`	Check `CONCATFLOW_API_KEY`. The key may be revoked.
403	`partition_keys_mismatch`	Send exactly the keys of the isolation. `err.body.detail.expected` lists them.
409	`door_closed`	Turn the per-user door on in Doors.
409	`isolation_unsigned`	Sign the isolation in Isolation.
409	`not_published`	Publish the assistant.

The full list is in Errors.

Embedded assistant

Private databases

Before you start

1. Install the server SDK

2. Add a session route

3. Show the assistant

What the token is

When the customer changes

Several partition keys

Errors

​Before you start

​1. Install the server SDK

​2. Add a session route

​3. Show the assistant

​What the token is

​When the customer changes

​Several partition keys

​Errors

Before you start

1. Install the server SDK

2. Add a session route

3. Show the assistant

What the token is

When the customer changes

Several partition keys

Errors