add draft of auth overview and oauth flow

Author: devalog

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
+## Choosing 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 handles 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 role-based permissions or API key injection. SSO works well for internal-only documentation where everyone should see the same content.
+
+**API Key Injection** (available with RBAC only) 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/sso.mdx

@@ -3,7 +3,7 @@ title: Single Sign-On
 subtitle: Enterprise authentication for secure access to your Fern dashboard
 ---
 
-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 Fern Docs site 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.
 
 ## What SSO unlocks