Customization

Access Control

Access ControlAlpha

Protect your documentation with JWT or OAuth to control who can access pages and API references.

Quick Start

Add accessControl to your docs.json:

docs.json

{
  "accessControl": {
    "provider": {
      "type": "jwt",
      "loginUrl": "https://your-auth-server.com/login",
      "callbackPath": "/auth/jwt-callback",
      "algorithm": "HS256",
      "secret": "$AUTH_SECRET",
      "groupsClaim": "groups"
    },
    "defaultAccess": "public",
    "rules": [
      { "match": "/api/**", "access": "protected" },
      { "match": "/admin/**", "access": "protected", "groups": ["admin"] }
    ],
    "deploy": {
      "platform": "node-edge"
    },
    "session": {
      "maxAge": 86400,
      "cookieName": "xyd-auth-token"
    }
  }
}

Claims and Groups

Use the groupsClaim field to read user groups for access control. How groups are provided depends on the provider type.

Claim	Type	Required	Description
`sub`	`string`	Yes	User identifier
`exp`	`number`	Yes	Expiration (Unix timestamp in seconds)
`iat`	`number`	Yes	Issued-at time
`groups`	`string[]`	For group access	Groups/roles (key name must match `groupsClaim`)

Example JWT payload:

{
  "sub": "user-123",
  "groups": ["admin", "staff"],
  "exp": 1735689600,
  "iat": 1735603200
}

Auth server example (Node.js):

import { createHmac } from "node:crypto v2";

const JWT_SECRET = process.env.AUTH_SECRET;

function signJWT(payload) {
  const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" }))
    .toString("base64url");
  const body = Buffer.from(JSON.stringify({
    ...payload,
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 86400,
  })).toString("base64url");
  const sig = createHmac("sha256", JWT_SECRET)
    .update(`${header}.${body}`)
    .digest("base64url");
  return `${header}.${body}.${sig}`;
}

// After user authenticates:
const token = signJWT({ sub: user.id, groups: user.groups });
const callbackUrl = `${DOCS_URL}/auth/jwt-callback?token=${token}&redirect=${redirect}`;
res.redirect(302, callbackUrl);

Info

If your JWT uses roles instead of groups, set groupsClaim: roles in docs.json.

Security Model

Layer	Protection	Platform
Layer 1 (default)	SSR exclusion + client-side auth. Content not in HTML source.	Any static host
Layer 2 (deploy)	Server-side JWT verification. Content never served to unauthorized.	Node.js, Netlify, Vercel, Cloudflare

Page-Level Access

Frontmatter

Override access on individual pages:

---
title: Admin Guide
public: false
accessGroups: ["admin"]
---

Field	Effect
`public: true`	Always public, even if `defaultAccess` is `"protected"`
`public: false`	Always protected, even if `defaultAccess` is `"public"`
`accessGroups: ["admin"]`	Requires membership in at least one listed group

Pattern Rules

Match pages by glob pattern in docs.json:

{
  "rules": [
    { "match": "/guides/**", "access": "public" },
    { "match": "/api/**", "access": "protected" },
    { "match": "/admin/**", "access": "protected", "groups": ["admin"] }
  ]
}

Rules are evaluated in order — first match wins.

Evaluation Priority

Frontmatter (highest) — public / accessGroups in page metadata
Pattern rules — rules array in docs.json
Default access (lowest) — defaultAccess: "public" | "protected"

Deploy Adapters

For production deployments, enable server-side protection:

docs.json

{
  "accessControl": {
    "deploy": {
      "platform": "node-edge"
    }
  }
}

With node-edge, xyd build generates a server.mjs in your build output:

xyd build   # generates .xyd/build/client/server.mjs
AUTH_SECRET=your-secret node .xyd/build/client/server.mjs
# or: xyd serve

The server verifies JWT signatures (HS256), checks access rules on every request, and returns 302 for unauthorized users.

Environment Variables

Variable	Required	Description
`AUTH_SECRET`	Yes (for JWT)	JWT signing secret (≥32 characters)
`PORT`	No	Server port (default: 3000)

Session Configuration

{
  "session": {
    "maxAge": 86400,
    "cookieName": "xyd-auth-token"
  }
}

xyd provides a built-in login page at /login. Customize it:

Feature Availability

Some features behave differently when you enable authentication. Protected pages are automatically excluded from search results, sidebar navigation, sitemap, and llms.txt for unauthorized users.

Feature	Public (no auth)	Fully authenticated	Partially authenticated
Search	Full support	Filtered by auth state	Filtered by auth state
Sidebar	Full support	Filtered by groups	Filtered by groups
Sitemap	Full support	Protected pages excluded	Protected pages excluded
llms.txt	Full support	Protected pages excluded	Protected pages excluded
Prev/Next links	Full support	Filtered by access	Filtered by access
HTML source	Full content	Empty shell (SSR exclusion)	Protected pages: empty shell
JS chunks	All accessible	Blocked by deploy adapter	Protected chunks blocked

Examples

Edit page

Plugins Theme API