Anonymous run api access sessions

agents-docs/_snippets/auth/RunApiAuthModes.mdx

@@ -34,6 +34,55 @@ This mode is for development only. Never use in production as it bypasses all se
 
 </Tab>
 
+<Tab title="Anonymous Sessions">
+
+For public-facing widgets where users don't need to sign in. Provides stable identity for conversation history, analytics, and rate limiting.
+
+**1. Setup the Auth Client:**
+
+```typescript
+import { createAuthClient } from 'better-auth/client';
+import { anonymousClient } from 'better-auth/client/plugins';
+
+export const authClient = createAuthClient({
+  baseURL: 'https://your-api.example.com',
+  plugins: [anonymousClient()],
+});
+```
+
+**2. Initialize Session:**
+
+```typescript
+async function initAnonymousSession() {
+  let session = await authClient.getSession();
+
+  if (!session.data) {
+    // Create new anonymous session
+    const result = await authClient.signIn.anonymous();
+    session = { data: result.data };
+  }
+
+  // distinctId is stable across sessions - use for analytics
+  const distinctId = session.data.user.id;
+  const sessionToken = session.data.session.token;
+
+  return { distinctId, sessionToken };
+}
+```
+
+**3. Request Headers:**
+
+```http
+X-API-Key: <your_api_key>
+Authorization: Bearer <session_token>
+```
+
+<Tip>
+The `distinctId` (user ID) is public and safe to use for analytics. The session token proves ownership and enables conversation history persistence.
+</Tip>
+
+</Tab>
+
 </Tabs>
 
 See [Authentication → Run API](/api-reference/authentication/run-api) for more details.

agents-docs/content/talk-to-your-agents/(chat-components)/javascript/chat-button.mdx

@@ -36,6 +36,51 @@ The chat button component is a simple way to trigger the Inkeep chat bubble in y
   </Step>
 </Steps>
 
+## Anonymous Sessions
+
+For public widgets where users don't sign in, but you want stable identity for conversation history and analytics:
+
+```html
+<script type="module">
+  import { createAuthClient } from "https://cdn.jsdelivr.net/npm/better-auth@1.0/dist/client/index.mjs";
+  import { anonymousClient } from "https://cdn.jsdelivr.net/npm/better-auth@1.0/dist/client/plugins/anonymous.mjs";
+
+  const authClient = createAuthClient({
+    baseURL: "https://your-api.example.com",
+    plugins: [anonymousClient()],
+  });
+
+  async function initWidget() {
+    let session = await authClient.getSession();
+    if (!session.data) {
+      const result = await authClient.signIn.anonymous();
+      session = { data: result.data };
+    }
+
+    localStorage.setItem("distinctId", session.data.user.id);
+
+    const config = {
+      aiChatSettings: {
+        agentUrl: "https://your-api.example.com/api/chat",
+        apiKey: "YOUR_API_KEY",
+        headers: {
+          Authorization: `Bearer ${session.data.session.token}`,
+        },
+      },
+    };
+
+    Inkeep.ChatButton(config);
+  }
+
+  initWidget();
+</script>
+```
+
+**Key benefits:**
+- Conversation history persists across page reloads
+- `distinctId` is stable for analytics tracking
+- Sessions auto-refresh (7-day expiry)
+
 ## Config
 
 <AutoTypeTable

agents-docs/content/talk-to-your-agents/(chat-components)/javascript/custom-trigger.mdx

@@ -60,6 +60,62 @@ Custom triggers give you complete control over how users open Inkeep modals in y
   </Step>
 </Steps>
 
+## Anonymous Sessions
+
+For public widgets where users don't sign in, but you want stable identity for conversation history and analytics:
+
+```html
+<script type="module">
+  import { createAuthClient } from "https://cdn.jsdelivr.net/npm/better-auth@1.0/dist/client/index.mjs";
+  import { anonymousClient } from "https://cdn.jsdelivr.net/npm/better-auth@1.0/dist/client/plugins/anonymous.mjs";
+
+  const authClient = createAuthClient({
+    baseURL: "https://your-api.example.com",
+    plugins: [anonymousClient()],
+  });
+
+  async function initWidget() {
+    let session = await authClient.getSession();
+    if (!session.data) {
+      const result = await authClient.signIn.anonymous();
+      session = { data: result.data };
+    }
+
+    localStorage.setItem("distinctId", session.data.user.id);
+
+    const config = {
+      aiChatSettings: {
+        agentUrl: "https://your-api.example.com/api/chat",
+        apiKey: "YOUR_API_KEY",
+        headers: {
+          Authorization: `Bearer ${session.data.session.token}`,
+        },
+      },
+      openSettings: {
+        onOpenChange: handleOpenChange,
+      },
+    };
+
+    const modalChat = Inkeep.ModalChat(config);
+
+    function handleOpenChange(newOpen) {
+      modalChat.update({ openSettings: { isOpen: newOpen } });
+    }
+
+    document.querySelector("#chat-button").addEventListener("click", () => {
+      modalChat.update({ openSettings: { isOpen: true } });
+    });
+  }
+
+  initWidget();
+</script>
+```
+
+**Key benefits:**
+- Conversation history persists across page reloads
+- `distinctId` is stable for analytics tracking
+- Sessions auto-refresh (7-day expiry)
+
 ## Config
 
 <AutoTypeTable

agents-docs/content/talk-to-your-agents/(chat-components)/javascript/embedded-chat.mdx

@@ -54,6 +54,53 @@ The EmbeddedChat widget provides a fully embedded chat interface that you can in
   </Step>
 </Steps>
 
+## Anonymous Sessions
+
+For public widgets where users don't sign in, but you want stable identity for conversation history and analytics:
+
+```html
+<script type="module">
+  import { createAuthClient } from "https://cdn.jsdelivr.net/npm/better-auth@1.0/dist/client/index.mjs";
+  import { anonymousClient } from "https://cdn.jsdelivr.net/npm/better-auth@1.0/dist/client/plugins/anonymous.mjs";
+
+  const authClient = createAuthClient({
+    baseURL: "https://your-api.example.com",
+    plugins: [anonymousClient()],
+  });
+
+  async function initWidget() {
+    // Get or create anonymous session
+    let session = await authClient.getSession();
+    if (!session.data) {
+      const result = await authClient.signIn.anonymous();
+      session = { data: result.data };
+    }
+
+    // Store distinctId for analytics (public, stable identifier)
+    localStorage.setItem("distinctId", session.data.user.id);
+
+    const config = {
+      aiChatSettings: {
+        agentUrl: "https://your-api.example.com/api/chat",
+        apiKey: "YOUR_API_KEY",
+        headers: {
+          Authorization: `Bearer ${session.data.session.token}`,
+        },
+      },
+    };
+
+    Inkeep.EmbeddedChat("#ikp-embedded-chat-target", config);
+  }
+
+  initWidget();
+</script>
+```
+
+**Key benefits:**
+- Conversation history persists across page reloads
+- `distinctId` is stable for analytics tracking
+- Sessions auto-refresh (7-day expiry)
+
 ## Config
 
 <AutoTypeTable

agents-docs/content/talk-to-your-agents/(chat-components)/javascript/side-bar-chat.mdx

@@ -73,6 +73,51 @@ The SidebarChat widget provides a slide-out panel interface for conversing with
   </Step>
 </Steps>
 
+## Anonymous Sessions
+
+For public widgets where users don't sign in, but you want stable identity for conversation history and analytics:
+
+```html
+<script type="module">
+  import { createAuthClient } from "https://cdn.jsdelivr.net/npm/better-auth@1.0/dist/client/index.mjs";
+  import { anonymousClient } from "https://cdn.jsdelivr.net/npm/better-auth@1.0/dist/client/plugins/anonymous.mjs";
+
+  const authClient = createAuthClient({
+    baseURL: "https://your-api.example.com",
+    plugins: [anonymousClient()],
+  });
+
+  async function initWidget() {
+    let session = await authClient.getSession();
+    if (!session.data) {
+      const result = await authClient.signIn.anonymous();
+      session = { data: result.data };
+    }
+
+    localStorage.setItem("distinctId", session.data.user.id);
+
+    const config = {
+      aiChatSettings: {
+        agentUrl: "https://your-api.example.com/api/chat",
+        apiKey: "YOUR_API_KEY",
+        headers: {
+          Authorization: `Bearer ${session.data.session.token}`,
+        },
+      },
+    };
+
+    Inkeep.SidebarChat("#ikp-sidebar-chat-target", config);
+  }
+
+  initWidget();
+</script>
+```
+
+**Key benefits:**
+- Conversation history persists across page reloads
+- `distinctId` is stable for analytics tracking
+- Sessions auto-refresh (7-day expiry)
+
 ## Config
 
 <AutoTypeTable

agents-docs/content/talk-to-your-agents/(chat-components)/react/chat-button.mdx

@@ -82,6 +82,63 @@ pnpm add @inkeep/agents-ui
     **Note:** Run your API server with `ENVIRONMENT=development` to bypass authentication.
 
   </Tab>
+
+  <Tab title="Anonymous">
+
+    For public widgets where users don't sign in, but you want stable identity for conversation history and analytics:
+
+    ```tsx
+    import {
+      InkeepChatButton,
+      type InkeepChatButtonProps,
+    } from "@inkeep/agents-ui";
+    import { createAuthClient } from "better-auth/client";
+    import { anonymousClient } from "better-auth/client/plugins";
+    import { useEffect, useState } from "react";
+
+    const authClient = createAuthClient({
+      baseURL: process.env.REACT_APP_AUTH_URL,
+      plugins: [anonymousClient()],
+    });
+
+    const ChatButton = () => {
+      const [sessionToken, setSessionToken] = useState<string | null>(null);
+
+      useEffect(() => {
+        async function initSession() {
+          let session = await authClient.getSession();
+          if (!session.data) {
+            const result = await authClient.signIn.anonymous();
+            session = { data: result.data };
+          }
+          localStorage.setItem("distinctId", session.data.user.id);
+          setSessionToken(session.data.session.token);
+        }
+        initSession();
+      }, []);
+
+      if (!sessionToken) return null;
+
+      const buttonProps: InkeepChatButtonProps = {
+        aiChatSettings: {
+          agentUrl: "https://your-api.example.com/api/chat",
+          apiKey: process.env.REACT_APP_INKEEP_API_KEY,
+          headers: {
+            Authorization: `Bearer ${sessionToken}`,
+          },
+        },
+      };
+
+      return <InkeepChatButton {...buttonProps} />;
+    };
+    ```
+
+    **Key benefits:**
+    - Conversation history persists across page reloads
+    - `distinctId` is stable for analytics tracking
+    - Sessions auto-refresh (7-day expiry)
+
+  </Tab>
 </Tabs>
 
 ## Props