Private docs

Private docs let you keep some or all of your docs behind a sign-in. Staff can sign in with company SSO; customers can reuse the session they already have in your product. You decide who reads what with groups and rules in orbitdocs.config.ts.

Private docs need a serverCopy Anchor Link

A static host serves every file to anyone. So access is enforced by the server that serves the docs. It checks every request before a page, a spec or a search index leaves it.

For Next server mode, proxy.ts looks like this:

import { orbitProxy } from '@orbitdocs/next/proxy';

export default orbitProxy();

export const config = {
  matcher: ['/((?!_next/static|_next/image).*)'],
};

Without access (and without ai) in the config, the proxy lets every request through, so it is safe to keep.

Set up private docsCopy Anchor Link

import { defineConfig } from '@orbitdocs/next/config';

export default defineConfig({
  site: { title: 'Acme' },
  access: {
    mode: 'public',
    groups: {
      staff: { domains: ['acme.com'] },
      partners: { emails: ['pat@partner.io'], idpGroups: ['partner-devs'] },
    },
    rules: [{ path: '/internal/*', groups: ['staff'] }],
    providers: [
      { type: 'google', clientId: '1234.apps.googleusercontent.com', clientSecretEnv: 'GOOGLE_CLIENT_SECRET', hostedDomain: 'acme.com' },
    ],
    appSession: {
      type: 'supabase',
      projectUrl: 'https://abcd1234.supabase.co',
      loginUrl: 'https://app.acme.com/login',
    },
  },
  output: { mode: 'server', basePath: '' },
});

ORBITDOCS_AUTH_SECRET=<at least 32 random characters, e.g. from `openssl rand -hex 32`>
GOOGLE_CLIENT_SECRET=<from Google Cloud>

npx orbitdocs build

How a request is checkedCopy Anchor Link

1. Requests to /_auth/* are the sign-in routes (below). They are always public, like /_next/*, /favicon.ico, /icon.svg and /robots.txt.
2. Otherwise the server finds the first config rule whose path matches, plus the page's frontmatter access and its API's apis[].access. The reader must satisfy all of them, so the stricter one always wins. If none applies, the page is public in public mode and needs sign-in in private mode.
3. A reader satisfies a group list when they are in one of its groups. * means any signed-in reader.
4. A signed-out reader asking for a page is sent to /_auth/login?next=<page>. Data requests (the search index, a spec, a Markdown file) get a plain 401.
5. A signed-in reader without access gets a "You don't have access to this page" screen, with a link to sign in with another account.

public and private modes:

• mode: 'public' (default): only pages matched by a rule, by access frontmatter or by apis[].access need sign-in.
• mode: 'private': every page needs sign-in. Rules can still narrow some pages to some groups.

Sign-in routesCopy Anchor Link

All routes live under the base path, so /docs/_auth/login when output.basePath is /docs.

next must be a path on the same site, so the sign-in flow can't redirect readers to another domain.

SessionsCopy Anchor Link

The docs keep no database. After sign-in, the reader's email, name, groups and personalization are put in a signed cookie:

• od_session: an HS256 JWT signed with the session secret. HttpOnly, SameSite=Lax, Secure on HTTPS, scoped to the base path. It expires after session.maxAgeHours.
• od_flow: short-lived state for one SSO round trip (10 minutes).

access: {
  // …
  session: { secretEnv: 'DOCS_SESSION_SECRET', maxAgeHours: 8 },
},

Readers signed in through your product's session are different: the docs verify your product's cookie again at least every 5 minutes. See Your product's session.

Customize the sign-in pageCopy Anchor Link

access: {
  // …
  loginPage: {
    title: 'Sign in to Acme docs',
    description: 'Use your Acme account or company SSO.',
  },
},

The page shows your product's button first (when appSession is set), then "or", then one button per SSO provider. It shows your site.logo (the light and dark images follow the reader's system theme; site.title without a logo) and uses theme.accent. The favicon is site.favicon, or the app's icon.png; the Apple touch icon is apple-icon.png. The logo and both icons are served to signed-out readers too, even in private mode. The "no access" page looks the same.

Behind a proxyCopy Anchor Link

The callback URL and the Secure cookie flag come from the request's origin. The server reads X-Forwarded-Proto and X-Forwarded-Host, then Host. If your proxy rewrites them, set the public URL:

mountOrbitDocs(app, {
  root: join(__dirname, '../docs/out'),
  path: '/docs',
  auth: { publicUrl: 'https://api.acme.com' },
});

mountOrbitDocs supports the Express adapter only. auth: false turns private docs off even when the build has access rules.

Access optionsCopy Anchor Link

Next stepsCopy Anchor Link