Access Control

Control who can view your documentation with flexible access control options.

Overview

Control who can view your documentation by configuring access control settings. You can make your documentation fully public, fully private, or a mix of both.

Access control is configured in the dashboard under Settings > Access Control and takes effect after you publish (or re-publish) your documentation.

If you store your documentation source in your own Git repository, keep that repository private so the source content is not publicly visible. Access control settings apply only to the deployed documentation site, not to the visibility of your Git repository.

Access modes

Public: Anyone can access your documentation. No authentication required.
Private: All pages require authentication. Choose from Password, JWT, or OAuth 2.0.
Partial: A mix of public and protected pages. Choose from Password, JWT, or OAuth 2.0 for the protected pages.

Authentication methods

Documentation.AI offers three authentication methods to protect your documentation:

Method	Available in	User-level access	Personalization
Password	Private, Partial	No (shared password)	No
JWT	Private, Partial	Yes (per-user roles)	Yes
OAuth 2.0	Private, Partial	Yes (per-user roles)	Yes

Password

Simple shared password protection. Best for internal docs shared with a small team.

In Private mode, all pages are protected.
In Partial mode, you configure which pages are public and which require the password.

Set up password authentication ->

JWT

Integrate with your existing authentication system using JSON Web Tokens. Supports per-user access roles and personalization. Available in Private and Partial modes.

Set up JWT authentication ->

OAuth 2.0

Integrate with OAuth 2.0 or OpenID Connect (OIDC) providers like Okta, Auth0, or Azure AD. Supports per-user access roles and personalization. Available in Private and Partial modes.

Set up OAuth 2.0 authentication ->

Role-based access control

With JWT and OAuth 2.0 authentication, you can control which pages each user can see using the access-roles property in your documentation.json navigation.

Users whose token includes at least one matching role can view the page. Pages without access-roles are visible to all authenticated users. A special wildcard role * grants access to all pages.

Role-based access control is available with JWT and OAuth 2.0 authentication in both Private and Partial modes.

How it works

Add the access-roles property to any navigation node in your documentation.json. It accepts an array of role name strings.

{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              { "title": "Introduction", "path": "intro" },
              { "title": "Quick Start", "path": "quick-start" }
            ]
          },
          {
            "group": "Engineering",
            "access-roles": ["engineering", "platform"],
            "pages": [
              { "title": "Architecture", "path": "engineering/arch" },
              {
                "title": "Runbooks",
                "path": "engineering/runbooks",
                "access-roles": ["sre"]
              }
            ]
          }
        ]
      },
      {
        "tab": "Admin",
        "access-roles": ["admin"],
        "groups": [
          {
            "group": "Operations",
            "pages": [
              { "title": "Deploy Guide", "path": "admin/deploy" }
            ]
          }
        ]
      }
    ]
  }
}

In this example:

Introduction and Quick Start are visible to all authenticated users (no access-roles set).
Architecture is visible to users with the engineering or platform role (inherited from the group).
Runbooks is visible only to users with the sre role (overrides the group's roles).
Deploy Guide is visible only to users with the admin role (inherited from the tab).

Inheritance rules

Default: If no access-roles is set anywhere, pages are visible to all authenticated users.
Closest wins: The closest (nearest) explicit access-roles in the navigation tree determines which roles are required for that node and its subtree.
Explicit override: A child node can override its parent by setting its own access-roles.
Empty array: Setting access-roles: [] explicitly makes a node visible to all authenticated users, even if a parent has role restrictions.

When a user authenticates with JWT or OAuth 2.0, the sidebar, search results, page navigation, and raw markdown export (/md/) are automatically filtered based on their roles. Pages the user cannot access do not appear anywhere in the UI, and the page renderer blocks direct URL access to restricted content.

If a user navigates directly to a restricted URL, they see an "Access Restricted" page instead of the content.

JWT claims format

Your JWT or OAuth provider must include the accessRoles field in the token claims:

{
  "host": "docs.example.com",
  "firstname": "Alice",
  "company": "Acme Inc",
  "accessRoles": ["engineering", "sre"]
}

The field names are fixed: host, firstname, company, and accessRoles.

Per-user content in MDX

With JWT or OAuth 2.0 authentication, you can personalize page content for each authenticated reader using these variables directly in your MDX:

{user.firstname}: the reader's first name from the token claims
{user.company}: the reader's company from the token claims
{user.accessRoles}: the reader's assigned access roles

Anonymous visitors see blank values for these variables, so you can safely use them in Partial mode pages that are also visible to the public.

The signed-in reader's identity is also available as window.dai.user in custom scripts, so you can build personalized experiences beyond standard MDX content.

Was this page helpful?