Password Protection

Sometimes you want your documentation online, discoverable, versioned in Git, but not visible to the world. Runbooks, pre-release guides, partner-only docs, early-access features. Password protection gives you a single shared passphrase that gates either your whole site or a specific set of pages, without moving anything out of your existing repo.

Which mode should I pick?

Jamdesk has two modes for password protection. Pick one based on what's public and what isn't.

Both modes share the same dashboard card, the same unlock screen, and the same rotation and revoke controls. You can switch between them at any time 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

Whole-site mode has one escape hatch: you can keep specific pages public even while the rest of the site is gated. This is how you publish a marketing landing page or a signup form alongside private docs.

You've got three ways to mark a page public, and they all merge into the same allow-list on each build.

Frontmatter is the most granular option. Add public: true to any .mdx file and only that page escapes the gate:

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

Navigation groups cover a whole section at once. Set public: true on a group or tab in your docs.json navigation, and every page under it is public. Handy for a "Marketing" tab that sits 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[] handle anything frontmatter and navigation can't: top-level landing pages, dynamically-generated routes, or an entire 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). A bare / is rejected on validation: if Jamdesk honored it, a single typo could silently unlock your whole site. After each build, the dashboard card shows the resolved allow-list, so you can sanity-check what the build actually picked up.

Protect just a few pages

Specific-pages mode is the opposite workflow: everything is public by default, and you 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

When someone hits a gated page, they get a centered unlock card with no sidebar, no chrome, and no indication of what's behind the door besides the site name and an optional hint.

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

Wrong passwords render the same card with an error message, a fresh input, and a small delay between attempts. An incorrect password and a request without a password both land on the same screen, so nothing on the page distinguishes "password wrong" from "no password entered yet."

Once a visitor enters the correct password, they get a signed cookie and can browse normally until the session expires or you revoke it.

Rotating and revoking sessions

Passwords get shared. People leave. You'll want to change it eventually.

Open the Password Protection card, type a new passphrase in the Rotate password field, and click Save new password. Everyone with the old password is locked out on their next request; everyone with the new password gets in. Rotation takes effect immediately and doesn't require a rebuild.

If you just want to force-logout every active session without changing the passphrase (say, someone's laptop went missing), click Revoke all sessions instead. It bumps a server-side version counter, which invalidates every cookie issued before the bump. Visitors re-enter the current password and get back in.

Disabling protection

Protection is driven by docs.json, so turning it off means editing the file 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.

On the next build, Jamdesk deletes the stored password hash and flips the card back to Off. No "dormant" state lingers. If you re-enable protection later, you'll need to pick a fresh password.

Precedence rules

A single page can be touched by several signals at once. The resolution order, from most to least specific:

• If auth.password.enabled is true, the whole site is gated. private: true on individual pages becomes redundant.
• If a page is marked both public: true and private: true, public wins. The safer default is the one that doesn't accidentally leak a page.
• Frontmatter public: true, nav-group public: true, and auth.password.public[] globs all merge into one allow-list. No "most specific wins" rule. If any signal says a page is public, it's public.
• If auth.password.private[] is set but auth.password.enabled is not, Jamdesk activates specific-pages mode automatically. You don't need to do anything else.

How sessions and rate limiting work

Three questions come up with any new auth system.

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, so any 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. Both are enforced before the scrypt hash check so 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, so you can preview gated pages without knowing the password. This is deliberate: you're the author, you already have the keys to the repo, and blocking the local preview on a password wall would be friction for no security benefit.

If you want to verify the actual gate, hit the deployed site at <slug>.jamdesk.app (or your custom domain) from a browser window that doesn't have the cookie yet.

Troubleshooting

What's Next?