> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

1. You define **access groups** in your `docs.json`
2. Each group specifies which pages its members can access
3. Readers authenticate via your identity provider (Okta, Auth0, Google Workspace, your own IdP, etc.)
4. JWT claims include the reader's group membership
5. 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:

1. If the page is in `publicPaths`, it is served without authentication
2. If no valid JWT is present, redirect to the login URL
3. Extract group membership from the JWT claims
4. Check if any of the reader's groups include the requested page
5. 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:

1. Create test users in your identity provider with different group memberships
2. Use the dashboard **Auth Preview** to simulate access for each group
3. Verify that protected pages return 403 for unauthorized users
4. Check that navigation correctly hides inaccessible pages