Access Control
Choose how readers reach your docs: fully public, password-gated, mixed public/private, your own login via JWT, or SSO. Pick the one that fits your audience.
Jamdesk gives you five ways to control who can read your docs.
Pick the right approach
| Approach | Use when | Setup |
|---|---|---|
| Fully public | External-facing product docs, open-source projects, anything you want indexed and shareable. | Default. No configuration needed. |
| Whole-site password | Everything is internal: engineering runbooks, partner-only docs, an unreleased product. One shared passphrase gates the whole site. | auth.password.enabled: true in docs.json + set password in dashboard. See Password Protection. |
| Mixed (some pages private) | Most docs are public. A few are internal (a runbook, a beta feature, an internal API reference). | Add private: true to frontmatter on internal pages, or list them under auth.password.private[]. See Password Protection. |
| Your own login (JWT) | Readers already sign in to your product. Your backend signs a short-lived token for each reader. Jamdesk turns it into a session. Pages can be limited to groups you name in the token. | auth.jwt.enabled: true plus a loginUrl in docs.json, and a signing key from the dashboard. Included on every plan. See JWT Authentication. |
| SSO (Enterprise) | Readers should sign in with your existing identity provider: no shared passwords, an audit trail, and deprovisioning by removing the user. | Enterprise plan. See SSO. |
Switch approaches anytime by editing docs.json and pushing. Switching from whole-site to mixed (or vice versa) takes one build.
Common patterns
Internal and external docs in one project
You don't need two projects for internal docs behind a login and a public site for customers. Use mixed mode in one Jamdesk project:
---
title: Incident Runbook
private: true
---Pages with private: true are gated. Everything else stays public. You keep one repo, one build, and one dashboard. The unlock screen only appears on a gated page.
For larger internal sections, list the paths in docs.json instead of marking each file. auth.password.private[] activates specific-pages mode automatically. Don't add enabled: true alongside it. That turns on whole-site mode, the opposite of what you want here.
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/internal/**", "/admin/runbook"]
}
}
}Two separate projects
Use two projects only when the audiences need fully different branding, separate custom domains, separate analytics, or different plan tiers. Examples: a public docs site at docs.acme.com and a separate internal wiki at internal.acme.com. Maintenance cost is higher: two builds, two dashboards, two domains.
Per-user access through your own login
A shared password is a step backwards when your customers already have accounts with you. It gets forwarded, it never expires on its own, and it can't tell one customer from another. JWT authentication sends a signed-in reader who opens your docs to a URL on your side. Your backend signs a token. Jamdesk creates a session for that reader. Readers need no Jamdesk account. There is no shared secret to forward.
The token can also carry groups. Add groups: ["admin"] to a page's frontmatter. Only visitors whose token lists admin can open it or see it in the navigation. Everyone else gets a 404. The page doesn't give away that it exists.
---
title: Enterprise audit log API
groups: ["enterprise"]
---Pair it with public paths for the parts of the site that should stay open, such as a changelog or a status page.
SSO for the docs site
Readers on Enterprise plans sign in with your identity provider (Okta, Google Workspace, Azure AD, etc.) instead of typing a shared password. Use it when you need an audit trail of who read what, or when offboarding must revoke docs access immediately. See SSO for an overview and how to contact sales.
Editors vs readers
Jamdesk has three separate access roles:
| Role | What they do | How access is granted |
|---|---|---|
| Editors | Write and update MDX content. | Docs are edited by committing MDX to your connected GitHub repo. Your GitHub repo permissions decide who can commit. A push only builds if the person who pushed is a member of the Jamdesk project (matched by their linked GitHub account or their email) or an automation account you've authorized. A push from anyone else shows as a failed build. The project owner gets an email. See GitHub. |
| Readers | View the published docs site. | Everyone (public), anyone with the password (password mode), anyone your login flow signs a token for (JWT), or anyone authenticated via your IdP (SSO). |
| Dashboard team members | Manage builds, analytics, and project settings in the Jamdesk dashboard. | Invited via Project Settings → Members in the dashboard. Membership is also what lets a person's pushes build. See Team Members. |
A teammate can hold any mix of these roles. One rule links them: an editor's pushes only build if the editor is also a team member.