Identity

import { auth } from "@clerk/nextjs/server";
import { medianIdentity } from "@mediansh/agent-tools";

export const { GET } = medianIdentity(async () => (await auth()).userId);

<MedianSupport identity="/api/median/identity" />

Without identity, a conversation belongs to the browser. The widget keeps a random token in localStorage, so one person on two devices is two visitors with two histories. A signed user.id ties the conversation to the person on every device.

Median only believes an id that arrives with a hash your server signed.

Serve the identity route

medianIdentity builds a GET route that returns the median_pk_ id and the signed in person, already signed. It reads MEDIAN_KEY from the server environment, so the browser needs no Median value of its own.

Return an object to show your team more than an id:

import { medianIdentity } from "@mediansh/agent-tools";

export const { GET } = medianIdentity(async (request) => {
  const session = await getSession(request);
  if (!session) return null;

  return {
    id: session.user.id,
    name: session.user.name,
    email: session.user.email,
    avatarUrl: session.user.image,
    metadata: { plan: session.org.plan },
  };
});

medianIdentity(resolver, options) takes an optional key that replaces MEDIAN_KEY. signIn and apiUrl are for site sign-in.

Resolver return values

Empty name and email values are dropped. An avatarUrl that is not https is dropped. An empty metadata object is dropped.

Response

Every response carries cache-control: private, no-store, max-age=0 and vary: cookie, authorization.

The request the widget sends

• A session kept in a cookie works as is. A session kept only in a bearer token never reaches the resolver. Use Sign it yourself instead.
• medianIdentity sets no CORS headers. Serve the route from the same origin as the page.
• Components that mount together share one request. MedianSupport, MedianSupportModal, MedianFeedback, MedianContactForm and useMedianContact all take identity.

<MedianSupport identity="/api/median/identity" />
<MedianFeedback identity="/api/median/identity">
  <button>Share feedback</button>
</MedianFeedback>

Pass the key as well

<MedianSupport apiKey="median_pk_..." identity="/api/median/identity" />

A route fails when the request errors or answers with a status outside 200 to 299. A resolver that returns null or throws is not a failure.

Sign it yourself

Use this when your session lives where the widget renders, or when your server cannot serve a Web Request route. Sign on the server with the same MEDIAN_KEY the widget id came from.

On the server:

import { signMedianUser } from "@mediansh/agent-tools";

app.get("/api/me", async (req, res) => {
  const user = req.session.user;
  if (!user) return res.json(null);

  res.set("cache-control", "private, no-store");
  res.json({
    id: user.id,
    name: user.name,
    email: user.email,
    medianHash: await signMedianUser(user.id),
  });
});

In the browser:

const me = useMe(); // your own hook that reads /api/me

<MedianSupport
  apiKey={import.meta.env.VITE_MEDIAN_PUBLIC_KEY}
  user={
    me
      ? { id: me.id, hash: me.medianHash, name: me.name, email: me.email }
      : undefined
  }
/>;

• signMedianUser(userId, key?) reads MEDIAN_KEY when key is omitted. Call it on the server only.
• VITE_MEDIAN_PUBLIC_KEY holds the median_pk_ id from publicKeyFromMedianKey(MEDIAN_KEY). The id is safe in client code.
• Sign the exact string you pass as id. The check is character for character.
• Any server that answers GET with { apiKey, user }, where user carries hash, also works as an identity route.

Site sign-in

The same route signs visitors in to your public site, so the site and the widget share one customer. Return an email, and say where your login page is:

export const { GET } = medianIdentity(resolveUser, {
  signIn: (returnTo) => `/login?next=${encodeURIComponent(returnTo)}`,
});

Then pick Your app under Site → Sign-in and paste the route's URL. See Site sign-in.

Behavior

Nothing is stored until the visitor sends a first message. After that, a change of signed user syncs as it happens.

Require sign in

Use it for a product nobody uses signed out. Until somebody is signed in, the panel asks them to sign in, and no conversation is opened or read.

<MedianSupport
  identity="/api/median/identity"
  requireSignIn
  onSignIn={() => router.push("/login")}
/>

With a session you already have:

<MedianSupport
  apiKey="median_pk_..."
  user={session?.user}
  requireSignIn
  onSignIn={() => router.push("/login")}
/>

• Any field counts, not only id. A name or an email says somebody is there.
• Sign in shows only with onSignIn. Without it, the panel shows the same text and no button.
• With identity, the panel shows a loading state until the route answers, rather than inviting a signed in person to sign in.
• Pass user as soon as your session resolves. The panel shows the sign in state until it arrives.
• The launcher stays in the corner.
• Nothing is read while the panel is locked. There is no thread and no unread count.

:::warning requireSignIn controls what the widget shows. It does not stop a crafted request to the API. A signed hash is what proves who somebody is. :::

Reset on sign out

import { medianSupport } from "@mediansh/widget";

medianSupport.reset();

reset() removes this browser's session token and saved email. The next message starts a new, anonymous visitor. The old conversations stay in your inbox.

reset() also signs out the user the widget holds at that moment.

With user, call reset() before or after your own sign out. With identity, call it after, so the route already answers with nobody when it is read again.

A mounted widget reads the identity route when it mounts and when reset() runs. For a sign in that happens without a page load, give the widget a key that changes with the user, so it remounts and reads the route again.

:::warning Without reset(), the next person on that browser sees the previous person's conversation, and anything they send before signing in goes into it. :::

Troubleshooting