Merge pull request #124 from openai/docs-ia-redo

[docs] IA redo first pass

Author: jiwon-oai

packages/docs/astro.config.ts

@@ -41,18 +41,55 @@ const typeDocConfig: StarlightTypeDocOptions['typeDoc'] = {
 const sidebar = [
   { label: 'Overview', link: '/' },
   {
-    label: 'Guides',
+    label: 'Authenticate users',
+    collapsed: true,
     items: [
-      { label: 'Authentication', link: '/guides/authentication' },
       {
-        label: 'Theming & Customization',
-        link: '/guides/theming-customization',
+        label: 'Hosted backend (client secrets)',
+        link: '/guides/authenticate-hosted',
       },
-      { label: 'Methods', link: '/guides/methods' },
-      { label: 'Events', link: '/guides/events' },
-      { label: 'Client Tools', link: '/guides/client-tools' },
-      { label: 'Entity tagging', link: '/guides/entities' },
-      { label: 'Custom Backends', link: '/guides/custom-backends' },
+      {
+        label: 'Custom backend (custom fetch)',
+        link: '/guides/authenticate-custom',
+      },
+    ],
+  },
+  {
+    label: 'Customize',
+    collapsed: true,
+    items: [
+      { label: 'Overview', link: '/guides/customize' },
+      { label: 'Theme', link: '/guides/customize-theme' },
+      { label: 'Header & history', link: '/guides/customize-header-history' },
+      { label: 'Start screen', link: '/guides/customize-start-screen' },
+      { label: 'Composer', link: '/guides/customize-composer' },
+      {
+        label: 'Thread item actions',
+        link: '/guides/customize-thread-item-actions',
+      },
+    ],
+  },
+  {
+    label: 'Connect to your app',
+    collapsed: true,
+    items: [
+      { label: 'Register callbacks', link: '/guides/register-callbacks' },
+      { label: 'Call ChatKit methods', link: '/guides/methods' },
+      {
+        label: 'Handle runtime events',
+        link: '/guides/runtime-events',
+      },
+    ],
+  },
+  {
+    label: 'Go live',
+    collapsed: true,
+    items: [
+      { label: 'Overview', link: '/guides/go-live' },
+      { label: 'Provide domain keys', link: '/guides/provide-domain-keys' },
+      { label: 'Monitor logs', link: '/guides/monitor-logs' },
+      // { label: 'Update CSP settings', link: '/guides/update-csp-settings' },
+      // { label: 'Scope user data', link: '/guides/scope-user-data' },
       { label: 'Localization', link: '/guides/localization' },
     ],
   },

packages/docs/src/content/docs/guides/custom-backends.mdx renamed to packages/docs/src/content/docs/guides/authenticate-custom.mdx

@@ -1,18 +1,22 @@
 ---
-title: Custom backends
-description: Build a bespoke backend for ChatKit using your own stack.
+title: Authenticate users with a custom backend
+description: Inject headers and metadata with a custom fetch function.
 ---
 
 import { TabItem, Tabs } from '@astrojs/starlight/components';
 
-Use a custom backend when you need full control over routing, tools, memory, or security. Provide a custom fetch function to use for API requests and orchestrate model calls yourself.
+:::note[Note]
+This guide is for a **custom backend** using the ChatKit Python SDK.
+For the hosted backend, see [Authenticate users with a hosted backend](/chatkit-js/guides/authenticate-hosted).
+:::
 
-## Approaches
+To protect the ChatKit endpoints exposed by your server using the ChatKit Python SDK, use a custom fetch function to inject your own auth headers and metadata on every request.
 
-- Use the ChatKit Python SDK for fast integration
-- Or integrate directly with your model provider and implement compatible events
 
-## Configure ChatKit
+## Inject headers with `api.fetch`
+
+- Point ChatKit at your endpoint with `api.url`.
+- Add auth headers through the `fetch` override.
 
 <Tabs syncKey="language">
 <TabItem label="React">
@@ -33,17 +37,9 @@ Use a custom backend when you need full control over routing, tools, memory, or
               ...options.headers,
               "Authorization": `Bearer ${auth}`,
             },
-
-            // You can override any options here
           });
         },
 
-        // Required when attachments are enabled.
-        uploadStrategy: {
-          type: "direct",
-          uploadUrl: "https://your-domain.com/your/chatkit/api/upload",
-        }
-
         // Register your domain in the dashboard at
         // https://platform.openai.com/settings/organization/security/domain-allowlist
         domainKey: "your-domain-key",
@@ -70,23 +66,19 @@ Use a custom backend when you need full control over routing, tools, memory, or
               // Anything you do in this callback is invisible to ChatKit.
               "Authorization": `Bearer ${auth}`,
             },
-            // You can override any options here
           });
         },
         // Register your domain in the dashboard at
         // https://platform.openai.com/settings/organization/security/domain-allowlist
         domainKey: "your-domain-key",
-        // Required when attachments are enabled.
-        uploadStrategy: {
-          type: "direct",
-          uploadUrl: "https://your-domain.com/your/chatkit/api/upload",
-        }
       },
     });
   ```
 
 </TabItem>
 </Tabs>
 
+## Backend responsibilities
 
-
+- Validate every request (auth headers, cookies, or signed params) before invoking your agent.
+- Scope data to the requesting user and session; the ChatKit Python SDK does not define the concept of a "user" or "session".

packages/docs/src/content/docs/guides/authenticate-hosted.mdx

@@ -0,0 +1,92 @@
+---
+title: Authenticate users with a hosted backend
+description: Issue client secrets from your own server and pass them to ChatKit at runtime.
+---
+
+import { TabItem, Tabs } from '@astrojs/starlight/components';
+
+:::note[Note]
+This guide is for the **hosted backend**.
+For a custom backend, see [Authenticate users with a custom backend](/chatkit-js/guides/authenticate-custom).
+:::
+
+This guide shows how to mint short-lived ChatKit client secrets after authenticating users on your server and deliver them to the hosted backend at runtime.
+
+
+
+## Expose a ChatKit session endpoint from your server
+
+Your server issues client secrets after authenticating the user. Use the ChatKit Sessions API to create (and later refresh) secrets and return only the `client_secret` value to the browser.
+
+Your server should:
+- Authenticate the user (cookies, headers, tokens, etc.)
+- Call the [ChatKit sessions API](https://platform.openai.com/docs/api-reference/chatkit/sessions/create) to create a session
+- Return `client_secret` to your app/browser
+
+**FastAPI example**
+
+```py
+from fastapi import FastAPI, Depends
+from openai import OpenAI
+import os
+
+app = FastAPI()
+client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
+
+def require_user():
+    # Replace with your auth logic. Raise if unauthenticated.
+    return {"user_id": "user_123"}
+
+@app.post("/chatkit/session")
+def create_chatkit_session(user=Depends(require_user)):
+    session = client.beta.chatkit.sessions.create(
+      workflow={"id": workflow_id}, # your published Agent Builder workflow id
+      user=user["user_id"],
+      # chatkit_configuration, expires_after, rate_limits, ...
+    )
+    return {"client_secret": session.client_secret}
+```
+
+## Configure ChatKit with `getClientSecret`
+
+Wire your session endpoint into ChatKit. The callback pulls a fresh `client_secret` on mount and whenever ChatKit asks for a refresh.
+
+<Tabs syncKey="language">
+<TabItem label="React">
+  ```jsx
+    const chatkit = useChatKit({
+      api: {
+        async getClientSecret() {
+          const res = await fetch('/chatkit/session', { method: 'POST' });
+          const { client_secret } = await res.json();
+          return client_secret;
+        },
+      },
+    });
+  ```
+
+</TabItem>
+
+<TabItem label="Vanilla JS">
+
+  ```js
+    const chatkit = document.getElementById('my-chat');
+
+    chatkit.setOptions({
+      api: {
+        async getClientSecret() {
+          const res = await fetch('/api/chatkit/start', { method: 'POST' });
+          const { client_secret } = await res.json();
+          return client_secret;
+        },
+      },
+    });
+  ```
+
+</TabItem>
+</Tabs>
+
+## Operational notes
+
+- Keep the ChatKit sessions API settings (history, attachments, etc.) in sync with the options you pass to ChatKit.
+- `getClientSecret(currentClientSecret)` runs on mount and before expiry; use the presence of `currentClientSecret` to tell refreshes apart from first-time requests.