Role-Based Access Control
Control which documentation pages are visible to which readers using content access groups.
Overview
HolyDocs RBAC (Role-Based Access Control) lets you restrict access to specific documentation pages based on reader group membership. This is essential for documentation that includes internal-only content, partner-specific guides, or tiered product documentation.
Requirements
Content RBAC is available on Business and Enterprise plans. It requires authentication to be enabled on your doc site.
How It Works
- You define access groups in your
docs.json - Each group specifies which pages its members can access
- Readers authenticate via your identity provider (Okta, Auth0, Google Workspace, your own IdP, etc.)
- JWT claims include the reader's group membership
- HolyDocs checks group membership before serving each page
Configuration
Configure access groups in the auth section of docs.json:
json{ "auth": { "enabled": true, "provider": "clerk", "publicPaths": ["/", "/introduction", "/quickstart"], "groups": { "internal": { "label": "Internal Team", "pages": ["internal/*", "roadmap", "architecture"] }, "partners": { "label": "Partners", "pages": ["partner-guide", "api/partner-endpoints"] }, "enterprise": { "label": "Enterprise Customers", "pages": ["enterprise/*", "sla", "dedicated-support"] } } }}
Group Properties
| Property | Type | Description |
|---|---|---|
label | string | Human-readable group name |
pages | string[] | List of page paths or glob patterns accessible to this group |
Claims Mapping
HolyDocs reads group membership from JWT claims. Configure the claim path:
json{ "auth": { "claimsMapping": { "groups": "custom:doc_groups", "email": "email" } }}
The JWT should contain the groups claim as an array of group identifiers:
json{ "sub": "user_123", "email": "jane@company.com", "custom:doc_groups": ["internal", "enterprise"]}
Public Paths
Pages listed in publicPaths are accessible to all readers without authentication:
json{ "auth": { "publicPaths": ["/", "/introduction", "/quickstart", "/changelog"] }}
Public paths support exact matches only (no glob patterns). Use them for your landing page, getting started guide, and other pages that should be freely accessible.
Access Resolution
When a reader requests a page, HolyDocs resolves access in this order:
- If the page is in
publicPaths, it is served without authentication - If no valid JWT is present, redirect to the login URL
- Extract group membership from the JWT claims
- Check if any of the reader's groups include the requested page
- If access is granted, serve the page; otherwise return a 403 error
Search and AI Behavior
RBAC extends to search and AI features:
- Search results only include pages the authenticated reader can access
- AI assistant only retrieves context from accessible pages
- Page caching is disabled for auth-enabled projects to prevent content leakage
Auth-enabled projects skip all page and AI caching to prevent protected content from being served to unauthorized users. This may slightly increase response times.
Navigation Filtering
The sidebar navigation automatically filters out pages the reader cannot access. If an entire group's pages are inaccessible, the group heading is also hidden.
Testing RBAC
To test access control:
- Create test users in your identity provider with different group memberships
- Use the dashboard Auth Preview to simulate access for each group
- Verify that protected pages return 403 for unauthorized users
- Check that navigation correctly hides inaccessible pages