Reader auth

Reader auth (Layer 2) gates a customer’s published docs pages for their end users. The key property: Papervine never runs an identity provider for readers and never stores reader credentials. Instead, we verify a signed assertion produced by the customer’s own login system, then mint a short-lived docs session. The customer’s IdP does the hard part, so this is a much smaller security surface than real authentication.

The model matches the common “Authentication & Personalization” handshake, so an existing such configuration migrates unchanged. For how this differs from the dashboard account system, see platform auth and the auth overview.

Handshake methods

A handshake is how a reader who is already logged into the customer’s app proves it to the docs site. Three methods are supported, in build order.

The JWT payload

The signed payload is compatible with the standard reader-auth schema:

type User = {
  host?: string;          // must equal the docs domain — blocks token replay
  expiresAt?: number;     // docs session length (hours to weeks)
  groups?: string[];      // drives page access control
  content?: Record<string, any>;  // personalization, exposed as `user` in MDX
  apiPlaygroundInputs?: {          // pre-fills API keys in the playground
    server; header; query; cookie; path;
  };
};

When an unauthenticated reader follows a deep link into a gated page, the flow round-trips the intended path through ?redirect=%2Fintended-path so they land where they meant to after the handshake completes.

Setting up JWT

In Settings → Authentication, enable authentication and choose JWT. Papervine generates an Ed25519 keypair for the site: it shows you the private key to copy into your backend and keeps the matching public key to verify tokens with. Set your Login URL — the page where your own app signs readers in. The keypair is stable: switching between auth methods leaves it untouched, so only the Regenerate button rotates it — and regenerating invalidates the old key, so update your backend whenever you do.

Then, in your login flow, sign a token with that private key and redirect back to the docs:

import * as jose from "jose";

const key = await jose.importPKCS8(PAPERVINE_PRIVATE_KEY, "EdDSA");
const token = await new jose.SignJWT({
  host: "docs.example.com",          // must equal the docs domain
  expiresAt: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7, // 1 week

Because verification needs only the public key — never a shared secret — a leak of Papervine’s stored config can’t forge reader tokens, and the same property lets the gate move to the edge in the future.

Setting up the password method

The password method needs no backend integration — it’s a single shared secret, so it’s the fastest way to gate a site.

When a reader hits a gated page, Papervine sends them to the site’s /login, where they enter the password. On a correct, constant-time match it sets the same short-lived docs session cookie the JWT method uses, and bounces them back to the page they wanted. The login form renders on whichever host serves the site — a subdomain ({slug}.papervine.io/login), the apex path form (/sites/{slug}/login), or a custom domain (docs.example.com/login).

Access control

Gating is default-deny: an auth-enabled site requires a valid reader session, and on top of that you gate individual pages by group.

• Gate by group with groups: ["admin"] in a page’s frontmatter — the reader must belong to at least one listed group (groups come from the handshake’s groups claim). A reader who isn’t in any listed group can’t reach the page and never sees it in the sidebar — it’s dropped from the nav entirely, so its existence doesn’t leak. Because groups come from the handshake, the password method (which has no per-user identity) can’t satisfy a groups: page — group gating needs the JWT or OAuth method.
• Opt a page out of group gating with public: true in its frontmatter — any reader who cleared the site’s sign-in sees it, regardless of groups.

A group or tab whose pages are all gated away from a reader disappears entirely — no empty heading, no teasing “Internal” tab. Access lives on the page; the sidebar and tabs are derived from what the reader can actually reach.

Enforcement happens at the node-level render chokepoint that serves tenant docs, before a page renders. That point — rather than edge middleware — is required because the per-site auth config is a database read the edge can’t do, the same constraint that governs custom-domain resolution. A gated site renders only to a reader holding a valid, site-bound docs session; otherwise it redirects to that site’s /login, carrying the intended path.

Search, the AI assistant, and MCP respect the same gate

A page’s content can leave the renderer through three other doors — full-text search (Cmd-K), the AI assistant (which retrieves pages to ground its answers), and the generated MCP server (which exposes the docs as tools to external AI clients). All three honor the same per-page access as the sidebar, so a reader can never pull — or have the assistant cite — a page they couldn’t open directly:

• Search returns only pages the reader can access; gated hits are filtered out of results.
• The assistant retrieves and reads only accessible pages, so its answers and citations stay within what the reader is allowed to see.
• MCP clients connect without a reader session, so on a gated site they see only the public (un-gated) subset — group-restricted pages are invisible to search, reading, and listing over MCP. Reading a restricted page returns the same “not found” as a missing one.
• llms.txt / llms-full.txt (the AI-discovery feed) is likewise anonymous, so a gated site publishes only its public pages there — the full-corpus dump never includes gated bodies.
• The export-all view requires a signed-in reader, and the exported document contains only the pages that reader can access — a reader without a group can’t export the pages it covers.

On a site without reader auth, none of this changes anything: every page is public, so all of these behave exactly as before.

Personalization

The content blob from the handshake is exposed as a user variable in MDX scope (threaded through src/libathe third-party MDX serializer package.tsx), so a page can render conditionally per reader or per group — for example, showing different content to an admin group.