Site sign-in

Sign visitors in to your public site with their account in your product, from one route, or by signing the token yourself.

Your public site can sign visitors in with the account they already have in your product. Their site chat and their widget chat become one history, and your tools know who they are. This page is the developer half: the route, the token, and the OpenID Connect details.

To pick a method and set it up in the dashboard, see Choose how visitors sign in in the help center.

Your app

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

export const { GET } = medianIdentity(
  async () => {
    const user = await currentUser();
    if (!user) return null;
    return {
      id: user.id,
      email: user.primaryEmailAddress?.emailAddress,
      name: user.fullName ?? undefined,
      avatarUrl: user.imageUrl,
    };
  },
  {
    signIn: (returnTo) =>
      `/sign-in?redirect_url=${encodeURIComponent(returnTo)}`,
  },
);

This is the route the widget’s identity prop reads. If you have one, add email and signIn to it.

How it works

1. The site sends the visitor to your route with ?median_request=<id>.
2. Signed in, the route signs a token and sends them to Median. Signed out, it sends them to signIn(returnTo), and your login brings them back to the route.
3. Median checks the token and returns the visitor to the page they started on, signed in.

Without the query parameter, the route answers the widget as before.

Resolver

Options

Other servers

medianSiteRedirect builds the redirect for a server without Web Request and Response:

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

app.get("/median/sign-in", async (req, res) => {
  const user = req.session.user;
  if (!user) {
    return res.redirect(`/login?next=${encodeURIComponent(req.originalUrl)}`);
  }
  res.set("cache-control", "no-store");
  res.redirect(
    await medianSiteRedirect(String(req.query.median_request), {
      id: user.id,
      email: user.email,
      name: user.name,
    }),
  );
});

medianSiteRedirect(request, null) sends a signed out visitor back to the site instead.

The token

For a language without the SDK. Redirect to https://api.median.sh/sites/sign-in?token=<jwt>, or to https://api.median.sh/sites/sign-in?request=<median_request>&error=signed_out when nobody is signed in.

median_pk_ is publicKeyFromMedianKey(MEDIAN_KEY). Each token works once.

OpenID Connect

Setup happens at your provider and on Site → Sign-in. The steps and the issuer URL for each provider are in the help center. What Median does with the provider:

Sessions

API and CLI

MCP: median.site.signIn() and setSignIn(...). The client secret is never returned.

Errors from your route

Problems visitors and admins see, like a provider refusing the sign-in, are in Fix public site problems.