JWT authentication

If your product already has its own login system, JWT authentication lets you gate your docs behind it instead of handing out a shared passphrase. Your backend signs a short-lived token when a signed-in user clicks through to the docs; Jamdesk verifies it once, mints a session, and the visitor browses normally from then on — no separate Jamdesk account, no password to distribute.

How this differs from password protection

Password protection gives every visitor the same shared passphrase — good for internal docs, staging previews, or a single partner audience. JWT authentication is per-user: each visitor's identity, session length, and page access come from a token your backend signs, so you can tie docs access to your existing customer accounts, plans, or roles instead of one shared secret.

The two modes are mutually exclusive — auth.password and auth.jwt cannot both be enabled at once. See Migrating from password protection below if you're switching from one to the other.

Setup steps

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*"]
    }
  }
}

git add docs.json
git commit -m "Turn on JWT authentication"
git push

Integrate your login flow

When a signed-in user clicks through to your docs, your backend signs a JWT and redirects the browser to the docs site's callback URL with the token in the URL fragment (after the #) — fragments never reach your server logs or any reverse proxy, since browsers don't send them in the request.

The token must be signed with EdDSA (Ed25519, matching the key you generated in the dashboard), and its exp claim should be no more than about 10 seconds in the future. This isn't a session length — it's a handshake window. The actual session length is controlled separately by the expiresAt field in the payload (see the payload reference below).

import { SignJWT, importPKCS8 } from "jose";

// Store this in your secret manager — it's the private key Jamdesk showed
// you once when you generated it in Project Settings.
const privateKey = await importPKCS8(process.env.JAMDESK_JWT_PRIVATE_KEY!, "EdDSA");

async function signDocsToken(user: { groups: string[] }) {
  return new SignJWT({
    host: "acme.jamdesk.app", // or your custom domain, e.g. "docs.example.com"
    expiresAt: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7, // 7-day session
    groups: user.groups,
    apiPlaygroundInputs: {
      header: { Authorization: `Bearer ${user.apiToken}` },
    },
  })
    .setProtectedHeader({ alg: "EdDSA" })
    .setExpirationTime("10s") // handshake window, not session length
    .sign(privateKey);
}

// In your "open docs" route/button handler:
app.get("/docs-login", requireAuth, async (req, res) => {
  const token = await signDocsToken(req.user);
  const redirect = req.query.redirect ?? "/";
  res.redirect(
    `https://acme.jamdesk.app/_jd/auth/callback?redirect=${encodeURIComponent(
      String(redirect)
    )}#${token}`
  );
});

import time
import jwt  # PyJWT >= 2.4, with the cryptography extra installed

with open("jamdesk_jwt_private_key.pem", "rb") as f:
    PRIVATE_KEY = f.read()

def sign_docs_token(user):
    payload = {
        "host": "acme.jamdesk.app",  # or your custom domain
        "exp": int(time.time()) + 10,  # handshake window, not session length
        "expiresAt": int(time.time()) + 60 * 60 * 24 * 7,  # 7-day session
        "groups": user.groups,
        "apiPlaygroundInputs": {
            "header": {"Authorization": f"Bearer {user.api_token}"},
        },
    }
    return jwt.encode(payload, PRIVATE_KEY, algorithm="EdDSA")

@app.route("/docs-login")
def docs_login():
    token = sign_docs_token(current_user)
    redirect_path = request.args.get("redirect", "/")
    return redirect(
        f"https://acme.jamdesk.app/_jd/auth/callback"
        f"?redirect={quote(redirect_path)}#{token}"
    )

Redirect flow

1. A visitor requests a protected page (say, /quickstart) without a valid session. Jamdesk responds with a redirect to {loginUrl}?redirect=%2Fquickstart.
2. Your login flow authenticates the visitor (however you normally do that), signs a JWT, and redirects them to https://<your-docs-host>/_jd/auth/callback?redirect=%2Fquickstart#<jwt>.
3. The callback page reads the token out of the fragment client-side and posts it to Jamdesk's token-exchange endpoint. Jamdesk verifies the signature and claims, and on success sets a signed session cookie.
4. The browser is redirected to the original destination — /quickstart — now with a valid session. The redirect value is preserved end-to-end so visitors land exactly where they started.

If your backend can't determine a redirect value (someone bookmarked your login page directly, for example), just omit it — Jamdesk falls back to /.

Public pages

Some pages should stay reachable without signing in — a status page, a public changelog, a marketing-adjacent landing page. Three ways to mark a page public, and they all merge into one allow-list:

Frontmatter, for one page at a time:

---
title: Changelog
public: true
---

Navigation groups, for a whole section:

{
  "navigation": {
    "groups": [
      { "group": "Changelog", "public": true, "pages": ["changelog"] }
    ]
  }
}

Explicit globs, under auth.jwt.public[]:

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*", "/status"]
    }
  }
}

Group-based access

Some pages should only be visible to certain authenticated users — an admin runbook, an enterprise-only reference. Add groups to a page's frontmatter:

---
title: Admin API Keys
groups: ["admin"]
---

A visitor's session carries the groups array your backend put in the JWT payload. If a page declares groups and the visitor's session doesn't intersect with that list, they get a 404 — not a 401 or an unlock screen. This is deliberate: a group-restricted page doesn't reveal its own existence to users outside the group.

A few precision points worth knowing:

• Group pages are excluded from the sitemap, search, AI chat, and MCP — even for users who ARE in the group. Exclusion from these discovery surfaces is a blanket build-time decision, not a per-visitor one. A member of the admin group can still open /admin/api-keys directly (by URL or internal link), but it won't turn up in search results, chat answers, or llms.txt. If you need a restricted page to be findable by its own audience, link to it explicitly from another page that audience can already reach.
• An empty groups: [] means no restriction at all — not "nobody can see this." If you want to remove a page's group restriction, delete the groups field entirely rather than setting it to an empty array.
• To restrict a page to nobody, unpublish it. There's no groups value that means "nobody" — group membership is additive (any overlap grants access), so an empty or nonsense group list is equivalent to no restriction.
• Localized copies inherit the base page's groups automatically, unless the translation declares its own groups in its frontmatter — so translating a restricted page doesn't accidentally make the translation public.
• Keep group names short. Groups travel inside the session cookie: up to 32 groups per session, 64 characters each. Exceeding either limit — more than 32 groups, or any single name over 64 characters — doesn't trim the list; it rejects the entire token (401, no session granted). Keep your backend's group list within the cap rather than relying on truncation.

API playground pre-fill

If your docs have an API playground, you can pre-fill it for signed-in visitors so they don't have to paste in their own API key. Include apiPlaygroundInputs in your JWT payload:

{
  "host": "acme.jamdesk.app",
  "apiPlaygroundInputs": {
    "header": { "Authorization": "Bearer sk_live_user_specific_token" },
    "query": { "org_id": "acme-corp" },
    "path": { "workspace_id": "ws_123" }
  }
}

• header.Authorization pre-fills the playground's auth field. A Bearer prefix is stripped automatically if present.
• query and path pre-fill any matching parameter names on the current endpoint.
• server and cookie sections are not supported in this release — only header, query, and path are applied.
• Pre-fill never overwrites a value the visitor has already typed into the playground.

Payload reference

Logout

Signed-in visitors get a Log out link in the docs header. It sends them to /_jd/auth/logout, which clears the session cookie and redirects to your loginUrl. Link to it directly from your own app if you want a "sign out of docs" affordance elsewhere too — it's a plain GET request, no body or headers required.

Feature behavior under auth

Troubleshooting

Security note

apiPlaygroundInputs — including any Authorization value you put in it — is readable by JavaScript running on your docs site, via the session-info endpoint that powers the playground pre-fill. This is the same trade-off Mintlify's playground pre-fill makes: convenient, but not a place for high-privilege secrets.

Send per-user, least-privilege credentials scoped to what that visitor is allowed to do — never an org-wide admin key. Treat anything you put in apiPlaygroundInputs as visible to the person browsing the docs, because it is.

Migrating from password protection

Switching from a shared password to JWT authentication doesn't require any downtime, and the site is never public at any point. Do it in this order:

{
  "auth": {
    "password": { "enabled": false },
    "jwt": { "enabled": true, "loginUrl": "https://app.example.com/docs-login" }
  }
}

What's Next?