Skip to main content
The documentation site is gated behind the platform login. When an unauthenticated visitor hits a private docs page, Papervine redirects them to a route on the platform app. The already-signed-in app asks the API to mint a short-lived JWT — over an ordinary authenticated request — and hands the browser back to the docs, signed in.

​
The handshake

The JWT rides in the URL fragment (#…), never a query param, so the token stays out of server logs — Papervine reads it client-side.

​
Why route it through the app

The minter authenticates from the Authorization header, exactly like every other API call — the platform app reads its own session and attaches it. That’s the whole point: the platform app (platform.pixwel.com) and the API (api.pixwel.com) are different hosts, and the session lives in a host-scoped cookie that a plain top-level navigation to the API would not carry. By having the app broker the request, the handshake works identically in dev and in production, and it covers both session types — legacy/token and Clerk — with no special cookie handling. If the visitor isn’t signed in, the /docs/auth route (which inherits the platform’s login gate) shows the login modal; once they authenticate, the app reloads back to /docs/auth and completes the mint.

​
The pieces

No new API route is needed — the catch-all /{:controller}/{:action} dispatches /session/docs to Session::docs. Papervine’s JWT login URL points at the app route, not the API.

​
The token

Signed EdDSA (Ed25519) with firebase/php-jwt. Claims: The redirect path is validated (must be site-relative) to prevent an open redirect.

​
Configuration

Point Papervine’s JWT login URL at the app route, and set two environment variables on the API (both issued from the Papervine dashboard): If the key or host is unset, the minter returns 503 docs_auth_unconfigured.

​
Role-based pages

The groups claim drives per-page visibility. A page restricted to a group uses frontmatter:
It’s an allow-list — a user outside the listed groups gets a 404, so the page is fully hidden, not just unlinked. Pages with no groups are visible to anyone past the docs login. The entire Engineering tab is tagged groups: ["admin"].
Group gating only activates once authentication is enabled — until then the markers are inert. Conversely, once auth is live, a page with a groups requirement 404s for any user without a matching group.

​
Setup checklist

1

Enterprise plan

Papervine JWT auth requires an Enterprise plan.
2

Generate the keypair

In the Papervine dashboard, generate the EdDSA keypair and set the JWT login URL to https://platform.pixwel.com/docs/auth. Store the private key as papervine_jwt_private_key and set papervine_docs_host.
3

Serve on a subdomain

Host the docs at docs.pixwel.com — auth isn’t supported on a path basepath like pixwel.com/docs.
4

Gate pages

Engineering pages already carry groups: ["admin"]; add the marker to any other page that should be admin-only.