Password Protection

Password protection gates docs that stay in Git but shouldn't be public: runbooks, pre-release guides, partner-only docs, early-access features. One shared passphrase gates your whole site or a set of pages. Nothing moves out of your repo.

Which mode should I pick?

Pick a mode based on what's public.

The dashboard card, unlock screen, and rotation and revoke controls are the same in either mode. Switch modes by editing docs.json and pushing.

Protect your whole site

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack"
    }
  }
}

git add docs.json
git commit -m "Turn on password protection"
git push

# Should respond with HTTP/1.1 401 and the unlock HTML
curl -I https://acme.jamdesk.app/

# Submit the password. On success, sets the jd_auth_<slug> cookie.
curl -i -X POST https://acme.jamdesk.app/jd/unlock \
  -d "password=your-passphrase&from=/"

Public exceptions

Keep specific pages public while the rest of the site is gated, for example a marketing landing page or a signup form.

Mark a page public in any of three ways. The build merges them into one allow-list.

Frontmatter is the most granular option. Add public: true to an .mdx file to make that page public:

---
title: Get started
public: true
---

Navigation groups cover a whole section. Set public: true on a group or tab in your docs.json navigation to make every page under it public. For example, a "Marketing" tab next to private engineering docs:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Marketing",
        "public": true,
        "groups": [
          {
            "group": "Overview",
            "pages": ["landing", "pricing", "changelog"]
          }
        ]
      },
      {
        "tab": "Internal",
        "groups": [
          { "group": "Runbooks", "pages": ["deploys", "oncall"] }
        ]
      }
    ]
  }
}

Explicit globs under auth.password.public[] cover what frontmatter and navigation can't: top-level landing pages, dynamically generated routes, or a subtree you'd rather not rewrite.

{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack",
      "public": [
        "/landing",
        "/pricing",
        "/marketing/**",
        "/blog/*"
      ]
    }
  }
}

Globs support * (one path segment) and ** (any depth). Validation rejects a bare /, which would unlock your whole site. The dashboard card shows the allow-list resolved by the last build.

Protect just a few pages

In specific-pages mode, everything is public by default. Opt individual pages into the gate.

---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---

{
  "auth": {
    "password": {
      "hint": "Ask the on-call engineer",
      "private": ["/admin/runbook", "/internal/api-keys"]
    }
  }
}

git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push

What visitors see

A gated page shows a centered unlock card with the site name and an optional hint. There is no sidebar or navigation.

The card is branded with your site's logo and primary color from docs.json. The password field has a reveal toggle and autofocus.

A wrong password renders the same card with an error message, a fresh input, and a small delay between attempts. Nothing on the page distinguishes "password wrong" from "no password entered yet."

The correct password sets a signed cookie. It lasts until the session expires or you revoke it.

AI tools and API keys

Tools that can't enter the password, such as an MCP client or a script that fetches llms.txt, can use a project API key instead. The key works for the MCP server, .md page URLs and the llms files. It never opens HTML pages or the AI chat.

Rotating and revoking sessions

Open the Password Protection card, type a new passphrase in the Rotate password field, and click Save new password. The old password stops working on the next request. Rotation takes effect immediately and doesn't require a rebuild.

To sign out every active session without changing the passphrase (say, a laptop went missing), click Revoke all sessions. It bumps a server-side version counter. Every cookie issued before the bump stops working. Visitors re-enter the current password.

Disabling protection

Turn protection off by editing docs.json and pushing.

• Whole site: remove auth.password.enabled (or set it to false).
• Specific pages: remove every private: true marker and clear auth.password.private.

The next build deletes the stored password hash and flips the card back to Off. Re-enabling protection later requires a new password.

Precedence rules

A page can match several signals. The resolution order, from most to least specific:

• auth.password.enabled: true gates the whole site. private: true on individual pages becomes redundant.
• A page marked public: true and private: true is public. Public wins.
• Frontmatter public: true, nav-group public: true, and auth.password.public[] globs merge into one allow-list. If any signal says a page is public, it's public.
• auth.password.private[] without auth.password.enabled activates specific-pages mode.

How sessions and rate limiting work

The session cookie. On a successful unlock, Jamdesk sets a cookie named jd_auth_<slug> (for example, jd_auth_acme). It's HttpOnly, Secure, SameSite=Lax, scoped to the host, and signed with HMAC-SHA256. The payload includes the project slug, the current version counter, and an expiration timestamp. Tampering fails validation. The default lifetime is 30 days, refreshed on each successful unlock.

Rate limiting. The unlock endpoint applies two counters per hour: 10 attempts per IP and 100 attempts per project. They run before the scrypt hash check. A brute-force attempt can't burn CPU or leak timing information. Hitting either limit returns 429 Too Many Requests with a Retry-After header.

Storage. Your password is hashed with scrypt and stored in the dashboard's Firestore. It never lands in your repo, your docs.json, or a build artifact. If you lose it, rotate. No recovery path exists.

Testing during local development

jamdesk dev runs your docs against the live R2 content and live config. Password protection is not enforced in the local dev server. You can preview gated pages without the password.

To test the gate, open the deployed site at <slug>.jamdesk.app (or your custom domain) in a browser window without the cookie.

Troubleshooting

What's Next?