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. Visitors never need a Jamdesk account or a shared password.

How this differs from password protection

Password protection gives every visitor the same shared passphrase, which works well 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. Docs access can follow 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, because browsers don't send them with 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. That's a handshake window, not a session length. 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), omit it and Jamdesk falls back to /.

Public pages

Some pages should stay reachable without signing in, such as a status page or a public changelog. There are 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, such as an admin runbook or 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 rather than a 401 or an unlock screen. This is deliberate: a group-restricted page doesn't reveal its own existence to users outside the group.

Details that affect how you use groups:

• 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 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 from another page that audience can already reach.
• An empty groups: [] means no restriction at all, not "nobody can see this." 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, and any overlap grants access.
• Localized copies inherit the base page's groups automatically, unless the translation declares its own groups in its frontmatter. 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 doesn't trim the list; Jamdesk rejects the entire token with a 401 and grants no session.

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. 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. You can also link to it directly from your own app if you want a "sign out of docs" link elsewhere. It's a plain GET request with 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. Pre-fill is convenient, but it is 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 requires no downtime, and the site stays gated throughout. Do it in this order:

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

What's next?