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 public, require authentication for all pages, or configure partial access control where some pages are public and others are protected.
Access control is configured in the dashboard under Settings → Access Control and takes effect after you publish (or re-publish) your documentation.
Access modes
Documentation.AI supports three access modes:
-
Public: Anyone can access your documentation. No authentication required.
-
Private: All pages require authentication to access.
-
Partial: Make some pages public and restrict access to others.
Authentication methods
Documentation.AI offers three authentication methods to protect your documentation:
Password authentication requires a Standard plan or higher. JWT and OAuth 2.0 authentication require an Enterprise plan or higher.
Password authentication is available on Standard plans or higher.
Password authentication provides simple access control using a shared password. It does not support user-level personalization or individual user tracking.
Set up
Choose an access mode
In your dashboard, go to Settings → Access Control and select one of:
-
Private to protect the entire site
-
Partial to make some pages public and protect the rest
Set a password
In Authentication Method, choose Password, then set a strong password.
-
If you already have a password configured, leaving the password field blank keeps the current password.
-
Use Clear password only if you intend to remove password protection.
Re-publish to apply changes
After saving your access control settings, re-publish your documentation so the deployed site uses the updated configuration.
Distribute access
Securely share the docs URL and password with authorized users.
Example
You host documentation at docs.example.com and want basic access control without managing individual user accounts. Use Password authentication and share the password with authorized teammates.
JWT authentication is available on Enterprise plans or higher.
Authenticate users with JSON Web Tokens (JWT). This method allows you to integrate your documentation with your existing authentication system and supports user-level personalization.
Prerequisites
-
An Enterprise plan or higher
-
An authentication system that can generate and sign JWTs
-
A backend service that can create redirect URLs back to your docs
Set up
Configure JWT settings in the dashboard
In your dashboard, go to Settings → Access Control and select Private or Partial mode.
In Authentication Method, choose JWT, then configure your login URL (your existing login flow).
Generate a signing key
Generate a key in the dashboard and store it securely where your backend can access it.
Rotate keys using your established security process (for example, during incident response or scheduled rotation).
Integrate the docs callback into your login flow
After a user successfully authenticates in your system:
-
Create a JWT for that user (per the format required by Documentation.AI).
-
Sign the JWT using the algorithm required by Documentation.AI.
-
Redirect the user back to your docs site using the callback URL shown in the dashboard, including the signed JWT (the dashboard will show the exact callback format).
Preserve the user's intended destination (recommended)
When an unauthenticated user tries to visit a protected page, preserve their target path through your login flow using a redirect query parameter, then redirect back to the docs callback URL with the same redirect.
Example
You host docs at docs.example.com and your company login is https://login.example.com. Configure JWT authentication so users sign in with your existing identity system, then return to the docs site.
OAuth 2.0 authentication is available on Enterprise plans or higher.
Authenticate users with OAuth 2.0 or OpenID Connect (OIDC). This method integrates with popular identity providers and supports user-level personalization.
Prerequisites
-
An Enterprise plan or higher
-
An OAuth 2.0 or OIDC provider that supports the Authorization Code flow
Set up
Configure OAuth in the dashboard
In your dashboard, go to Settings → Access Control and select Private or Partial mode.
In Authentication Method, choose OAuth 2.0, then configure:
-
Authorization URL
-
Token URL
-
Client ID
-
Client Secret
-
Scopes (optional, if your provider requires them)
-
User info URL (optional, if your flow needs a separate user info fetch)
-
Logout URL (optional)
Register the redirect URL with your provider
Copy the redirect/callback URL shown in the dashboard and add it to your OAuth provider's allowed redirect URLs.
Re-publish to apply changes
After saving your access control settings, re-publish your documentation so the deployed site uses the updated configuration.
Example
You host docs at docs.example.com and use an existing OAuth provider for user sign-in. Configure OAuth 2.0 authentication so visitors authenticate via your provider before accessing protected pages.
Partial access control
In Partial mode, Documentation.AI determines whether a page is Public or Protected using the public flag on navigation nodes. You can configure this using either the Web Editor or the Code Editor.
Inheritance rules
-
Default: If no
publicflag is set anywhere, pages are treated as Protected in partial mode. -
Closest wins: The closest (nearest) explicit
publicflag in the navigation tree determines the effective visibility for that node and its subtree. -
Explicit override: A child node can override its parent by setting its own
publicflag.
Visibility values
-
Inherit: Do not set
publicon the node (the effective value comes from the nearest parent that haspublic). -
Public:
public: true -
Protected:
public: false
Configure public pages in partial access control mode
You can make specific pages or groups public in two ways:
Use the Web Editor to visually configure which pages are public or protected.
Open the Web Editor
Navigate to your project dashboard and click on** Editor** to open the visual editor.
Navigate to the page or group
In the navigation panel, find the page or group you want to make public or protected.
Configure visibility
In the navigation, each page and group shows an icon (🌐,🔒) that indicates its visibility state. Click on the icon and change status to
-
Public to make it accessible without authentication
-
Protected to require authentication
-
Inherit to use the parent's setting
Publish changes
After configuring visibility for your pages, publish your documentation to apply the changes.
Changes made in the Web Editor are automatically synced to your documentation.json file.
Configure the public property directly in your documentation.json file.
Setting the public property
The public property is an optional boolean that can be set on any navigation node (containers like groups/dropdowns/tabs/etc., and individual pages).
{
"navigation": {
"groups": [
{
"group": "Guides",
"public": true,
"pages": [
{
"title": "Overview",
"path": "guides/overview"
},
{
"title": "Internal Runbook",
"path": "guides/internal-runbook",
"public": false
}
]
}
]
}
}
Semantics
-
public: true: Marks the node as public and makes its descendants public unless overridden. -
public: false: Marks the node as protected and makes its descendants protected unless overridden. -
No
publicfield**: The node inherits from its nearest parent that haspublic. If no parent has it, the default is protected in partial mode.
Steps to configure
Open documentation.json
Open the documentation.json file in your code editor.
Add the public property
Add the public property to the navigation nodes you want to configure.
Commit and push
Commit your changes and push to your repository. The changes will be applied on your next deployment.
Last updated 2 weeks ago