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

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

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

Access is decided per page, and it is default-deny: with auth enabled, every page requires a reader session unless its frontmatter opens it up. Nothing is configured in the dashboard — the pages themselves carry the rules, so access lives in your repository and changes through the same review as any other content change.

• Make a page public with public: true. It needs no session at all, so it stays shareable and indexable. This is what lets one site carry public documentation and internal pages.
• Gate by group with groups: ["admin"] — the reader must belong to at least one listed group (groups come from the handshake’s groups claim). A reader outside every 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.
• Say nothing and the page is available to any signed-in reader. This is the default, which is why enabling auth on a site with no public: true pages makes the whole site private.

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. A single page’s .md twin is the exception, because it’s a page request rather than a bulk dump: it honors the reader’s session, so a signed-in reader gets the Markdown for a page they can already read and an anonymous client gets the same 404 the HTML page gives.
• 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.