chore: improve rbac docs

fern/fern.config.json

@@ -1,4 +1,4 @@
 {
   "organization": "fern",
-  "version": "0.64.22"
-}
+  "version": "0.65.23"
+}

fern/products/docs/docs.yml

@@ -152,7 +152,7 @@ navigation:
     contents:
       - page: SSO
         path: ./pages/authentication/sso.mdx
-      - page: RBAC
+      - page: Role based access control (RBAC)
         path: ./pages/authentication/rbac.mdx
       - page: API Key Injection
         path: ./pages/api-references/autopopulate-api-key.mdx

fern/products/docs/pages/authentication/rbac.mdx

@@ -6,59 +6,88 @@ description: Learn how to restrict access to your documentation using role-based
 
 <Note>RBAC is part of the pro plan.</Note>
 
-Fern allows you to restrict parts of your navigation to individuals with specific roles. Below, we walk through each of the steps
-required to configure RBAC.
+## 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.
+
+Below, we walk through each of the steps required to configure RBAC.
+
+### Architecture diagram
+
+```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->>R: Redirect to login page
+            R->>A: Authenticate user
+        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
+```
+
+## Set up RBAC
 
 <Steps>
 ### Define all the `roles` in your docs.yml
 
-Start by defining all the different roles in your `docs.yml`. You can simply specify this under a `roles` key:
+Start by defining all the different roles in your `docs.yml`. You can specify this under a `roles` key:
 
 ```yml docs.yml
 roles:
-  - everyone # every user is given this role
-  - partners
-  - beta-users
-  - admins
-```
-
-<Info>The `everyone` role is a special role. Every user has this role.</Info>
-
-### 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.
-
-```yml docs.yml {7-8,14-16}
-navigation:
-  - tab: Documentation
-    layout:
-      - page: Overview
-        path: pages/overview.mdx
-      - section: Beta Release
-        viewers:
-          - beta-users
-  - tab: API Reference
-    layout:
-      - page: Overview
-        path: pages/overview.mdx
-      - section: Beta Release
-        viewers:
-          - partners
-          - admin
+ - everyone # every user is given this role
+ - partners
+ - beta-users
+ - admins
 ```
 
-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.
+<Info>
+The `everyone` role is special. Every user has this role (including unauthenticated users).
+</Info>
 
 ### 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.
+**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`.
 
 ```json
 {
@@ -68,6 +97,79 @@ with a key called roles.
 }
 ```
 
-<Note>Please reach out to [email protected] when you are on this step so we can provide you with a secret key.</Note>
+### Contact Fern for setup
+
+When you're ready to implement RBAC, **contact [email protected]** to receive your secret key for JWT signing.
+
+You'll also need to provide the URL where Fern should send unauthenticated users to log in.
+
+<Note>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.</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_.
+
+```yml docs.yml {6-7, 13-15}
+navigation:
+  - tab: Home
+    layout: 
+      - page: Welcome # this page is public
+        path: pages/welcome.mdx
+        viewer: 
+          - 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>