Update nav structure for Docs Authentication section, add info on OAuth key injection flow

fern/products/docs/docs.yml

@@ -168,13 +168,15 @@ navigation:
   - section: Authentication
     collapsed: true
     contents:
-      - page: SSO
-        path: ./pages/authentication/sso.mdx
+      - page: Overview
+        path: ./pages/authentication/overview.mdx
       - page: Role based access control (RBAC)
         path: ./pages/authentication/rbac.mdx
         slug: rbac
       - page: API Key Injection
         path: ./pages/api-references/autopopulate-api-key.mdx
+      - page: SSO
+        path: ./pages/authentication/sso.mdx
   - section: Enterprise
     collapsed: true
     contents:

fern/products/docs/pages/api-references/autopopulate-api-key.mdx

@@ -13,7 +13,17 @@ Fern can integrate with your authentication flow, allowing users to login and ha
 
 With this feature, you can **create new users of your API** directly from within your documentation. 
 
-## How it works
+## Integrating with your auth flow
+
+API key injection can work in two different ways depending on your company's authentication setup: **JWT or OAuth**. 
+
+* **JWT Flow:** You handle the entire auth flow and just give Fern a JWT cookie
+* **OAuth Flow:** You give Fern access, and Fern directly initiates the OAuth handshake process
+
+<AccordionGroup toc={true}>
+<Accordion title="JWT" toc={true}>
+
+### How the JWT flow works
 
 To enable this feature, you need to configure authentication so that Fern can securely retrieve API keys for your users. The process works as follows:
 
@@ -77,11 +87,49 @@ The JWT should have a structure similar to:
 
 </CodeBlocks>
 
-## Setting up auto-populated API keys
+#### Architecture diagram
+
+<Markdown src="/snippets/jwt-auth-diagram.mdx"/>
+
+#### Setting up auto-populated API keys
 
 - [ ] Reach out to Fern to get your secret key 
-- [ ] Send Fern the URL of your authentication page (this is where users will be redirected to after clicking the "Login" button in the API Explorer)
+- [ ] Send Fern the URL of your authentication page. This is where users will be redirected to after clicking the "Login" button in the API Explorer.
 - [ ] Add logic to your service to set the `fern_token` cookie when a user logs in
 
 <Tip>For an example of how to set up the `fern_token` cookie, see our demo implementation [here](https://github.com/fern-api/fern-platform/blob/app/packages/fern-docs/bundle/src/app/%5Bhost%5D/%5Bdomain%5D/api/fern-docs/auth/fern-token-demo/route.ts).</Tip>
 
+</Accordion>
+<Accordion title="OAuth" toc={true}>
+
+### How the OAuth flow works
+
+To enable this feature, you need to configure OAuth authentication so that Fern can securely retrieve API keys for your users through your OAuth provider. Here's how the process works:
+
+1. When a user clicks the "Login" button in the API Explorer, Fern initiates an OAuth flow by making a request to your authorization endpoint.
+1. The user is redirected to your OAuth provider's login page where they authenticate using your existing auth system.
+1. After successful authentication, your OAuth provider redirects back to Fern with an authorization code, which Fern exchanges for an access token at your token endpoint.
+1. Fern sets a `fern_token` cookie containing the user's authentication credentials and automatically populates their API key in the API Explorer.
+
+#### Architecture diagram
+
+<Markdown src="/snippets/oauth-diagram.mdx"/>
+
+#### Setting up auto-populated API keys
+
+To enable API key injection, you'll need to:
+- [ ] Set up an authenticated account for Fern so Fern can authorize users on your behalf. 
+- [ ] Configure your OAuth application to return user API keys when Fern requests them
+
+Then, you'll need to send Fern the following items:
+- The client ID and client secret for Fern's authenticated account
+- The URL of your authentication endpoint. This is where users will be redirected to after clicking the "Login" button in the API Explorer.
+- The URL of your token endpoint. This is where Fern exchanges codes for tokens. 
+
+</Accordion>
+</AccordionGroup>
+
+
+
+
+

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

@@ -0,0 +1,28 @@
+---
+title: Overview of authentication options
+description: Understand the different authentication options Fern offers
+---
+
+Fern offers two methods of authentication, Single Sign-On (SSO) and Role-Based Access Control (RBAC). 
+
+**For most situations, we recommend using RBAC** for granular access control over your documentation. RBAC works well for sites with multiple audiences (internal teams, partners, customers) and supports API key injection to auto-populate code examples.
+
+API key injection can be set up using either JWT or OAuth, depending on your existing authentication system.
+
+**SSO is simpler** but only provides basic login functionality - it doesn't support RBAC or API key injection. SSO works well for internal-only documentation where everyone should see the same content.
+
+
+
+Learn more about Fern's authentication options:
+
+<CardGroup cols={3}>
+  <Card title="Role-based access control" icon="fa-duotone fa-people-group" href="/docs/authentication/rbac">
+    Granular access for different audiences
+  </Card>
+  <Card title="API Key Injection" icon="fa-duotone fa-key" href="/docs/authentication/api-key-injection">
+    JWT or OAuth flows available
+  </Card>
+  <Card title="SSO" icon="fa-duotone fa-user-check" href="/docs/authentication/sso">
+    Basic functionality and simple setup
+  </Card>
+</CardGroup>

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

@@ -24,43 +24,6 @@ Role-based access control is helpful for scenarios such as:
 
 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->>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
-```
-
 ## Set up RBAC
 
 <Steps>
@@ -82,10 +45,16 @@ The `everyone` role is special. Every user has this role (including unauthentica
 
 ### 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.
+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.
 
+Below, we walk through each of the steps required to configure RBAC with 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, 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
@@ -96,11 +65,22 @@ login page.
 }
 ```
 
-### Contact Fern for setup
+<Markdown src="/snippets/jwt-auth-diagram.mdx"/>
 
-When you're ready to implement RBAC, **contact [email protected]** to receive your secret key for JWT signing.
+</Accordion>
+<Accordion title="OAuth">
+
+Fern initiates an OAuth flow when the user needs authentication, redirecting them to your authentication endpoint. Fern creates and sets the `fern-token` cookie after completing this flow. 
+You are responsible for configuring your OAuth endpoints to return user role information. 
+
+<Markdown src="/snippets/oauth-diagram.mdx"/>
+
+</Accordion>
+</AccordionGroup>
+
+### Contact Fern for setup
 
-You'll also need to provide the URL where Fern should send unauthenticated users to log in.
+When you're ready to implement RBAC, **contact [email protected]**.
 
 <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>
 

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

@@ -1,22 +1,41 @@
 ---
 title: Single Sign-On
-subtitle: Enterprise authentication for secure access to your Fern dashboard
+subtitle: Enterprise authentication for secure access to your docs
 ---
 
-Fern’s Single Sign-On (SSO) is an enterprise feature that lets your team securely access the Fern dashboard at `dashboard.buildwithfern.com` using your organization’s identity provider. This is designed for internal contributors, such as technical writers, product managers, or engineers, who need access to want to contribute to your documentation, view web analytics, or manage organizational settings.
+Fern’s Single Sign-On (SSO) is an enterprise feature that lets your team securely access your docs through your organization’s identity provider.
+
+<Note>SSO does not support Role-Based Access Control or API Key Injection.</Note>
 
 ## What SSO unlocks
 
-When SSO is enabled for your organization, authenticated users of Fern gain access to:
+When SSO is enabled for your organization, authenticated users of Fern can:
 
-- **Manage Users of your Organization**: Add teammates and configure settings for your organization
-- **Access Ask Fern Analytics**: See AI-assisted search usage and browse verbatim user questions
-- **View Web Analytics**: Track key site metrics, like page views and unique visitors **(coming soon)**
 - **Use the Visual Editor**: Make edits to your docs from the browser
+- **Send Authenticated Preview Links** Only authenticated users can view [preview links](docs/preview-publish/previewing-changes-locally)
 
 ## How it works
 
-Fern's SSO integration allows your team to use their existing corporate credentials to access the Fern dashboard. Instead of managing separate Fern accounts, users authenticate through your organization's identity provider and are automatically granted appropriate access to your Fern resources.
+Fern's SSO integration allows your team to use their existing corporate credentials to access your Fern Docs site. 
+
+### Architecture diagram
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant F as Fern Docs
+    participant I as Identity Provider
+
+    U->>F: Click "Login" 
+    F->>I: Redirect to SSO login
+
+    Note over I: User authenticates with corporate credentials
+
+    I->>I: Validate user credentials
+    I->>F: Redirect back with fern_token
+    F->>F: Grant access to organizational features
+    F->>U: Show docs site
+```
 
 ## Supported identity providers
 
@@ -25,6 +44,7 @@ Fern supports SSO integration with any identity provider that implements industr
 - **SAML 2.0**: Compatible with providers like Okta, OneLogin, Azure AD, and others
 - **OIDC (OpenID Connect)**: Works with Google Workspace, Auth0, and other OIDC-compliant providers
 
-<Note>
-SSO is available as part of the Enterprise plan. Reach out via Slack or [contact our team](https://buildwithfern.com/contact) to begin the SSO setup process.
-</Note>
+## Setting up SSO
+
+SSO is available as part of the Enterprise plan. Reach out via Slack or [contact our team](https://buildwithfern.com/contact) to begin the SSO setup process. Fern will work with one of your security administrators to connect to your identity provider.
+

fern/snippets/jwt-auth-diagram.mdx

@@ -0,0 +1,32 @@
+```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
+```

fern/snippets/oauth-diagram.mdx

@@ -0,0 +1,30 @@
+```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
+```