Role-based access control

Define all the roles in your docs.yml

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

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

Define viewers on parts of the navigation

Every navigation item (sections, pages, api references) can have a set of designated viewers. If you don’t specify viewers, then it defaults to everyone and the page is public.

1
navigation:
2
  - tab: Documentation
3
    layout:
4
      - page: Overview
5
        path: pages/overview.mdx
6
      - section: Beta Release
7
        viewers:
8
          - beta-users
9
  - tab: API Reference
10
    layout:
11
      - page: Overview
12
        path: pages/overview.mdx
13
      - section: Beta Release
14
        viewers:
15
          - partners
16
          - admin

The viewers are inherited by nested pieces of content. 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.

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.

Upon login, you must set a JWT for the user using a secret key that we will provide you with. The JWT must have a fern claim with a key called roles.

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