Access Control | NookDocs

NookDocs supports three access modes per project:

Mode	What happens	Plan
Public	Anyone with the URL reads every page. Default.	Free +
Site password	Visitors enter a shared password on first visit; cookie keeps them signed in for 30 days.	Pro +
Per-page private	Only pages with `private: true` in their MDX frontmatter require the password — the rest stay public.	Pro +

Where to manage

Project → Settings → Access. Pick a mode, set or rotate the password, save.

The password is stored as a PBKDF2-SHA256 hash with a per-row salt — we never see the plaintext after submit.

How the gate works

When a tenant request comes in:

The docs renderer looks up the project's access_mode.
site mode: every request checks for a valid nook_access cookie. Missing or expired → redirect to /access-gate?next=<url>&reason=site-gate.
page mode: only checks the cookie when the requested page's frontmatter has private: true. Public pages stay public.
Login: /access-gate shows a password form. POST to /api/v1/projects/<id>/access/login sets the cookie and returns the visitor to the original URL.
Cookie binding: the cookie's signature uses the password hash as the HMAC key. Rotating the password invalidates every outstanding cookie immediately — no separate revocation step.

Marking a page private

In page-level mode, drop the flag into your frontmatter:

---
title: Internal API Reference
private: true
---

# Internal API

This page only loads for visitors who have entered the site password.

Pages without private: true continue to render publicly.

Cookie details


Name	`nook_access`
Scope	Set on the tenant's domain (subdomain or custom domain)
TTL	30 days
Flags	`HttpOnly`, `Secure`, `SameSite=Lax`
Signature	HMAC-SHA256 of `<projectId>.<expiry>` keyed by the password hash

Rotating the password breaks every cookie — useful when revoking access.

Plan availability

Plan	Site password	Per-page private
Free	—	—
Pro	✅	✅
Team	✅	✅
Enterprise	✅	✅

Notes

This is a shared-password gate, not per-user authentication. SSO + per-user identity for docs ships in the Enterprise SSO release.
Search engine crawlers stop at /access-gate — gated docs are effectively noindex.
Free tier visitors still see the docs because Free defaults to public; downgrading from Pro keeps the existing mode + hash working until you switch back to public.

For LLMs

If you're an AI agent helping a user automate access control for their NookDocs site, here's the canonical recipe:

1. Frontmatter contract (page-mode only):

---
title: Internal Runbook
private: true
---

The private: true field is respected only when the project's mode is set to page. On site mode every page is gated; on public mode private is ignored.

A private page is absent from every surface that lists or quotes content, not just from the URL: the sidebar, site search (including the snippets under each result), llms.txt, llms-full.txt, the .md export, the RSS feed and the MCP server. A reader who cannot open the page cannot find its text anywhere either.

2. Programmatic login (test automation, headless agents):

POST https://<project-slug>.nookdocs.site/api/v1/projects/<project_id>/access/login
Content-Type: application/json

{ "password": "the-shared-password" }

Sets the nook_access cookie scoped to the tenant domain. Subsequent requests on the same cookie jar will pass the gate. Logout via DELETE on the same URL.

Status codes:

200 — cookie set, proceed
401 — wrong password
400 (not_gated) — project is public, login is unnecessary

3. Crawler / indexer behaviour:

Site-mode and page-mode gated URLs return a redirect to /access-gate. Crawlers that don't follow login forms will index nothing. If you're building a search index for your own org's docs, authenticate first then crawl.

Common mistakes:

Don't store the cookie value in plaintext config — it's bound to the password hash and rotates automatically when the password changes.
Don't assume private: true works on public mode — it's silently ignored. Set the project mode first.
Cookie TTL is 30 days; refresh by calling /access/login again before expiry if you need long-lived access.