# Role-based access control

> Learn how to restrict access to your documentation using role-based access control (RBAC)

<Warning title="Pro and Enterprise feature">
  This feature is available only for the [Pro and Enterprise plans](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).
</Warning>

## 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](/learn/docs/ai-features/ask-fern/overview) 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

<Steps>
  ### Define all the `roles` in your docs.yml

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

  ```yml docs.yml
  roles:
   - everyone # every user is given this role
   - partners
   - beta-users
   - admins
  ```

  ### Configure authentication via a `fern_token`

  Fern uses a [browser cookie](/learn/docs/security/overview) called `fern_token` to identify authenticated users and their roles. If this cookie isn't 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:

  <AccordionGroup>
    <Accordion title="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:

      ```json
      {
        "fern": {
          "roles": ["partners"]
        }
      }
      ```

      ```mermaid
      sequenceDiagram
          participant U as User
          participant F as Fern Docs
          participant R as Redirect URL
          participant A as Auth System

          U->>F: Visit restricted page
          F->>F: Check fern_token cookie
          
          alt Cookie exists
              F->>F: Decode JWT with secret key
              F->>F: Extract roles from JWT
              F->>F: Check if user has required role
              
              alt User has required role
                  F->>U: Show restricted content
              else User lacks required role
                  F->>U: User is shown a 404 page
              end
          else No cookie
              F->>R: Redirect to login page
              R->>A: Authenticate user
          end
          
          Note over A: User logs in
          
          A->>A: Generate JWT with roles
          A->>F: Set fern_token cookie
          F->>F: Validate JWT and roles
          F->>U: Show restricted content
      ```
    </Accordion>

    <Accordion title="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.

      ```mermaid
      sequenceDiagram
          participant U as User
          participant F as Fern Docs
          participant A as OAuth2 Provider
          U->>F: Visit restricted page
          F->>F: Check fern_token cookie
          
          alt Cookie exists
              F->>F: Decode cookie
              F->>F: Verify authentication credentials
              Note over F: Attempt to refresh the token, if expired
              
              alt User is properly authenticated
                  F->>U: Show restricted content
              else User is not properly authenticated
                  F->>U: User is shown a 404 page
              end
          else No cookie
              F->>A: Redirect to `/authenticate` endpoint
              A->>U: User authenticates
              U->>F: Authorization code is returned
              F->>A: Redirect to `/token` endpoint
              A->>A: Validate token request
              A->>F: Send authenticated access token
              F->>F: Set fern_token cookie
              F->>F: Verify authentication credentials
              F->>U: Show restricted content
          end
      ```
    </Accordion>
  </AccordionGroup>

  ### Contact Fern for setup

  When you're ready to implement RBAC, contact [support@buildwithfern.com](mailto:support@buildwithfern.com).

  <Note title="Optional">
    If you'd like restricted pages to be visible but locked to unauthenticated users (rather than completely hidden), notify Fern during this step.
  </Note>
</Steps>

### 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. To make content publicly accessible, explicitly set viewers to `everyone`.

```yml docs.yml {6-7, 13-15}
navigation:
  - tab: Home
    layout: 
      - page: Welcome # this page is public
        path: pages/welcome.mdx
        viewers: 
          - everyone 
  - tab: Documentation
    layout:
      - page: Overview # this page is visible to all logged-in users
        path: pages/overview.mdx 
      - section: Beta Release # this section is visible to beta-users and admins
        viewers:
          - beta-users
          - admins
        contents: 
          ...
```

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:

```mdx
<If roles={["beta-users"]}>
  <Callout>
    This callout is only visible to beta users.
  </Callout>
</If>
```

#### Multiple roles

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

```mdx
<If roles={["partners", "admins"]}>
  <Callout>
    This content is visible to both partners and admins.
  </Callout>
</If>
```

<Note>
  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.
</Note>