Authentication

Role-based access control

Control who can view your documentation
RBAC is part of the pro plan.

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.

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

If a user visits content not marked as visible to the everyone role, Fern will check for an authentication cookie to indicate what roles that user has. If the user does not have a role matching the viewers of the page, we will redirect them to the URL you provided during setup.

Set up RBAC

1

Define all the roles in your docs.yml

Start by defining all the different roles in your docs.yml. You can specify this under a roles key:

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

The everyone role is special. Every user has this role (including unauthenticated users).

2

Configure authentication via a fern_token

In this step, we will configure authentication so that Fern can understand what roles a particular user has.

Fern expects the user’s browser session to have a cookie called fern_token. If the cookie is not present, the user will be redirected to your company’s login page.

Below, we walk through each of the steps required to configure RBAC with either JWT or OAuth.

You are responsible for creating and setting the fern_token cookie in your authentication system. Upon login, you must set a JWT for the user using a secret key that we will provide. The JWT must have a fern claim with a key called roles.

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

Fern initiates an OAuth flow when the user needs authentication, redirecting them to your authentication endpoint. Fern creates and sets the fern-token cookie after completing this flow. You are responsible for configuring your OAuth endpoints to return user role information.

3

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), let us know during this step.

Access control within navigation

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.

docs.yml
1navigation:
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.