Role-based access control

RBAC is a feature of JWT and OAuth authentication. Once a user logs in through either method, Fern checks the fern_token cookie to determine their roles and controls access to pages, sections, and other navigation items accordingly.

RBAC is useful for partner docs, beta features, tiered access, and internal content. You can combine it with API key injection in a single token. When RBAC is configured, Ask Fern automatically respects these permissions.

Setup

To enable RBAC, follow the JWT or OAuth setup guide, then define your roles in docs.yml:

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

Every user automatically has the everyone role, including unauthenticated visitors. If a user lacks the required role or isn’t authenticated, Fern redirects them to your login page.

Restricting content

Once RBAC is configured, use viewers in your navigation and the <If /> component in your pages to control what each role can see.

In navigation

You can assign viewers to the following navigation items: products, versions, tabs, sections, pages, api references, and 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.

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.

In MDX pages

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>

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>