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>
+<Accordion title="JWT" toc={true}>
+
+### How it 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:
 
@@ -80,8 +90,38 @@ The JWT should have a structure similar to:
 ## 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 it 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 uses this token to retrieve the user's API key and automatically populates it in the API Explorer.
+
+### 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. Provide Fern with 
+- [ ] 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,26 @@
+---
+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.
+
+**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.
+
+**API Key Injection** can be set up using either JWT or OAuth, depending on your existing authentication system.
+
+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">
+    Set up API Key Injection using JWT or OAuth.
+  </Card>
+  <Card title="SSO" icon="fa-duotone fa-user-check" href="/docs/authentication/sso">
+    Set up a simple authentication system.
+  </Card>
+</CardGroup>

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

@@ -24,10 +24,12 @@ 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.
+Below, we walk through each of the steps required to configure RBAC with either JWT or OAuth.
 
-### Architecture diagram
+### Architecture diagrams
 
+<Tabs>
+  <Tab title="RBAC with JWT">
 ```mermaid
 sequenceDiagram
     participant U as User
@@ -61,6 +63,44 @@ sequenceDiagram
     F->>U: Show restricted content
 ```
 
+  </Tab>
+  <Tab title="RBAC with OAuth">
+
+```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
+```
+  </Tab>
+</Tabs>
+
+
+
 ## Set up RBAC
 
 <Steps>

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

@@ -1,9 +1,11 @@
 ---
 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. 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.
+
+<Note>SSO does not support Role-Based Access Control or API Key Injection.</Note>
 
 ## What SSO unlocks
 
@@ -13,10 +15,30 @@ When SSO is enabled for your organization, authenticated users of Fern gain acce
 - **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. Instead of managing separate Fern accounts, users authenticate through your organization's identity provider and are automatically granted appropriate access to your Fern resources.
+
+### 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 +47,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.
+