Role-based access control | Fern Documentation

Pro and Enterprise feature

This feature is available only for the Pro and Enterprise plans. To get started, reach out to support@buildwithfern.com.

Introduction

Fern allows you to restrict parts of your navigation to individuals with specific roles. RBAC enables you to create different levels of access for different user types within your documentation.

When RBAC is configured, Ask Fern automatically respects these permissions so users only receive answers from content they’re authorized to view.

Use cases

Role-based access control is helpful for scenarios such as:

Partner documentation: Provide exclusive API documentation to integration partners while keeping internal docs private
Beta features: Share new features with beta users before general release
Internal documentation: Restrict sensitive documentation to employees only
Tiered access: Offer different documentation levels based on subscription tiers
Customer-specific content: Show different documentation based on customer type or plan

How it works

Every user automatically has the everyone role, including unauthenticated visitors. Pages marked with the everyone role are publicly accessible without needing to log in.

If a user visits content that requires authentication (i.e., content not marked as visible to everyone), Fern checks for an authentication cookie to determine the user’s roles. If the user lacks the required role or isn’t authenticated, Fern redirects them to the login URL you provided during setup.

Set up RBAC

Define all the `roles` in your docs.yml

Start by using a roles key to define all the different roles:

docs.yml

1 roles:
2  - everyone # every user is given this role
3  - partners
4  - beta-users
5  - admins

Configure authentication via a `fern_token`

Fern uses a browser cookie called fern_token to identify authenticated users and their roles. If this cookie is not present when a user tries to access restricted content, Fern redirects them to your login page.

You can set up this authentication using either JWT or OAuth:

JWT

You are responsible for creating and setting the fern_token cookie in your authentication system.

Upon login, set a JWT for the user using a secret key that Fern provides. The JWT must include a fern claim with a roles array:

1 {
2   "fern": {
3     "roles": ["partners"]
4   }
5 }

OAuth

When a user needs authentication, Fern initiates an OAuth flow and redirects them to your authentication endpoint. You configure your OAuth endpoints to return user role information.

Contact Fern for setup

When you’re ready to implement RBAC, contact support@buildwithfern.com.

Optional

If you’d like restricted pages to be visible but locked to unauthenticated users (rather than completely hidden), notify Fern during this step.

You can designate viewers on the following navigation items:

products
versions
tabs
sections
pages
api references
changelogs

If you don’t specify viewers, the content will be visible to any authenticated user. To make content publicly accessible, explicitly set viewers to everyone.

docs.yml

1 navigation:
2   - tab: Home
3     layout: 
4       - page: Welcome # this page is public
5         path: pages/welcome.mdx
6         viewers: 
7           - everyone 
8   - tab: Documentation
9     layout:
10       - page: Overview # this page is visible to all logged-in users
11         path: pages/overview.mdx 
12       - section: Beta Release # this section is visible to beta-users and admins
13         viewers:
14           - beta-users
15           - admins
16         contents: 
17           ...

Viewership is inherited. For example, if a section can only be viewed by admins, then all its pages and nested sections can also only be viewed by admins.

Access control within MDX pages

You can restrict specific content within your MDX pages to users with certain roles. This allows you to show different content to different user types on the same page.

Basic usage

Use the <If /> component to conditionally render content based on user roles:

1 <If roles={["beta-users"]}>
2   <Callout>
3     This callout is only visible to beta users.
4   </Callout>
5 </If>

Multiple roles

You can specify multiple roles. Content will be visible to users who have any of the specified roles:

1 <If roles={["partners", "admins"]}>
2   <Callout>
3     This content is visible to both partners and admins.
4   </Callout>
5 </If>

The <If> component respects the same role inheritance rules as navigation items. If a user has access to a page, they can see all content on that page that matches their roles.