Role-based access control

RBAC controls access to pages, sections, and other navigation items based on user roles. It works with password protection, JWT, and OAuth authentication.

RBAC is useful for partner docs, beta features, tiered access, and internal content. You can combine it with API key injection when using JWT or OAuth authentication. When RBAC is configured, Ask Fern automatically respects these permissions. By default, restricted pages are completely hidden from unauthorized users — if you’d like them to be visible but locked instead, let Fern know during setup.

Setup

To enable RBAC, first set up an authentication method — password protection, JWT, or OAuth — 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. There is no limit on the number of roles you can define, unless you’re using password protection, which supports up to three.

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. You can specify one or multiple roles. Content is 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>

You can also combine roles with products and versions props.