Site sign-in

Signing in lets visitors post, vote, comment and follow on the feedback board, and keeps their support chat across devices. The help center never asks.

Pick one under Site → Sign-in. Admins and owners only. Switching signs out everyone who signed in another way.

Median accounts

The default. There is nothing to set up.

Your app

Visitors sign in with the account they already have in your product. Their site chat and their widget chat are one history.

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.

Add the route

Deploy it with MEDIAN_KEY set on the server. See Identity.

Paste its URL

Under Site → Sign-in, pick Your app, paste the route's full https URL, and press Use your app.

Try it

Open your site and press Sign in.

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

Create an app at your provider

A regular web application using the authorization code flow. Add the Redirect URI from Site → Sign-in to its allowed callback URLs: https://api.median.sh/sites/oidc/callback. Allow the openid, email and profile scopes.

Add its details

Pick OpenID Connect. Enter the issuer URL, client ID and client secret, and press Use OpenID Connect.

What signing in does

API and CLI

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

Troubleshooting