From 7042ebf9376b61c4b4f82c0b22b11d97d4785786 Mon Sep 17 00:00:00 2001
From: john <ahmednahima0@gmail.com>
Date: Wed, 13 May 2026 04:19:23 +0700
Subject: [PATCH] docs(sessions): enhance authentication details in session API
 descriptions

Updated the descriptions for GET and POST endpoints related to sessions to clarify authentication requirements. Added explicit instructions on using either `x-api-key` or `Authorization: Bearer <privy-access-token>`, and detailed the consequences of sending both or neither. Enhanced error descriptions for unauthorized access to provide clearer guidance on potential issues. This improves the overall clarity and usability of the API documentation.
---
 api-reference/openapi/sessions.json | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json
index 3b9fe1c..97f7cf1 100644
--- a/api-reference/openapi/sessions.json
+++ b/api-reference/openapi/sessions.json
@@ -83,7 +83,7 @@
     "/api/sessions/{sessionId}": {
       "get": {
         "summary": "Get session by id",
-        "description": "Returns a single agent session by its id.",
+        "description": "**Authentication:** Send **exactly one** of `x-api-key` or `Authorization: Bearer <privy-access-token>`. Sending **both** headers or **neither** yields **401** (Recoup API `validateAuthContext`). Returns a single agent session by its id.",
         "parameters": [
           {
             "name": "sessionId",
@@ -107,7 +107,7 @@
             }
           },
           "401": {
-            "description": "Unauthorized - invalid or missing API key / Bearer token",
+            "description": "Unauthorized — invalid or missing credentials, or ambiguous authentication (both `x-api-key` and `Authorization` were sent, or neither was sent). Response body uses `{ \"status\": \"error\", \"error\": \"...\" }`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -142,7 +142,7 @@
     "/api/sessions/{sessionId}/chats": {
       "get": {
         "summary": "List session chats",
-        "description": "Lists every chat in the given session as a `ChatSummary` (chat row plus per-account `hasUnread` and `isStreaming` flags), along with the caller's default model id. Chats are sorted by `createdAt` ascending.",
+        "description": "**Authentication:** Send **exactly one** of `x-api-key` or `Authorization: Bearer <privy-access-token>`. Sending **both** headers or **neither** yields **401** (Recoup API `validateAuthContext`). The session must exist (**404**) and belong to the authenticated account (**403**). Lists every chat in the given session as a `ChatSummary` (chat row plus per-account `hasUnread` and `isStreaming` flags), along with the caller's default model id. Chats are sorted by `createdAt` ascending.",
         "parameters": [
           {
             "name": "sessionId",
@@ -166,7 +166,7 @@
             }
           },
           "401": {
-            "description": "Unauthorized — invalid or missing API key / Bearer token.",
+            "description": "Unauthorized — invalid or missing credentials, or ambiguous authentication (both `x-api-key` and `Authorization` were sent, or neither was sent). Response body uses `{ \"status\": \"error\", \"error\": \"...\" }`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -199,7 +199,7 @@
       },
       "post": {
         "summary": "Create session chat",
-        "description": "Creates a new chat inside the given session. Callers may pass `{ id }` to claim a deterministic chat id — useful for optimistic UI flows where the client generates the id locally and then persists it. If a chat with that id already exists in **this** session the call is idempotent and returns the existing row; if it exists in **another** session, 409 is returned.",
+        "description": "**Authentication:** Same as `GET` on this path — **exactly one** of `x-api-key` or `Authorization: Bearer <privy-access-token>`; both or neither → **401** (`validateAuthContext`). Session must exist and be owned by the caller (**404** / **403**). Creates a new chat inside the given session. Callers may pass `{ id }` to claim a deterministic chat id — useful for optimistic UI flows where the client generates the id locally and then persists it. If a chat with that id already exists in **this** session the call is idempotent and returns the existing row; if it exists in **another** session, 409 is returned.",
         "parameters": [
           {
             "name": "sessionId",
@@ -243,7 +243,7 @@
             }
           },
           "401": {
-            "description": "Unauthorized — invalid or missing API key / Bearer token.",
+            "description": "Unauthorized — invalid or missing credentials, or ambiguous authentication (both `x-api-key` and `Authorization` were sent, or neither was sent). Response body uses `{ \"status\": \"error\", \"error\": \"...\" }`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -301,11 +301,13 @@
       "ApiKeyAuth": {
         "type": "apiKey",
         "in": "header",
-        "name": "x-api-key"
+        "name": "x-api-key",
+        "description": "Personal or organization API key for server-side and automation clients."
       },
       "BearerAuth": {
         "type": "http",
-        "scheme": "bearer"
+        "scheme": "bearer",
+        "description": "Privy-issued user access token (`Authorization: Bearer <token>`) for browser clients (e.g. Open Agents)."
       }
     },
     "schemas": {