From 2e81f1900da465f1e65c3edfe212be715d707448 Mon Sep 17 00:00:00 2001
From: Celia Chen <celia@openai.com>
Date: Fri, 7 Nov 2025 08:17:19 -0800
Subject: [PATCH] [App-server] Add auth v2 doc & update codex mcp interface
 auth section (#6353)

Added doc for auth v2 endpoints. Updated the auth section in Codex MCP
interface doc too.
---
 codex-rs/app-server/README.md        | 95 ++++++++++++++++++++++++++++
 codex-rs/docs/codex_mcp_interface.md |  9 +--
 2 files changed, 98 insertions(+), 6 deletions(-)

diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md
index 2eb8a1ad..ee94bd34 100644
--- a/codex-rs/app-server/README.md
+++ b/codex-rs/app-server/README.md
@@ -13,3 +13,98 @@ Currently, you can dump a TypeScript version of the schema using `codex generate
 ```
 codex generate-ts --out DIR
 ```
+
+## Auth endpoints (v2)
+
+The v2 JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.
+
+### Quick reference
+- `account/read` — fetch current account info; optionally refresh tokens.
+- `account/login/start` — begin login (`apiKey` or `chatgpt`).
+- `account/login/completed` (notify) — emitted when a login attempt finishes (success or error).
+- `account/login/cancel` — cancel a pending ChatGPT login by `loginId`.
+- `account/logout` — sign out; triggers `account/updated`.
+- `account/updated` (notify) — emitted whenever auth mode changes (`authMode`: `apikey`, `chatgpt`, or `null`).
+- `account/rateLimits/read` — fetch ChatGPT rate limits; updates arrive via `account/rateLimits/updated` (notify).
+
+### 1) Check auth state
+
+Request:
+```json
+{ "method": "account/read", "id": 1, "params": { "refreshToken": false } }
+```
+
+Response examples:
+```json
+{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": false } } // no auth needed
+{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": true } }  // auth needed
+{ "id": 1, "result": { "account": { "type": "apiKey" }, "requiresOpenaiAuth": true } }
+{ "id": 1, "result": { "account": { "type": "chatgpt", "email": "user@example.com", "planType": "pro" }, "requiresOpenaiAuth": true } }
+```
+
+Field notes:
+- `refreshToken` (bool): set `true` to force a token refresh.
+- `requiresOpenaiAuth` reflects the active provider; when `false`, Codex can run without OpenAI credentials.
+
+### 2) Log in with an API key
+
+1. Send:
+   ```json
+   { "method": "account/login/start", "id": 2, "params": { "type": "apiKey", "apiKey": "sk-…" } }
+   ```
+2. Expect:
+   ```json
+   { "id": 2, "result": { "type": "apiKey" } }
+   ```
+3. Notifications:
+   ```json
+   { "method": "account/login/completed", "params": { "loginId": null, "success": true, "error": null } }
+   { "method": "account/updated", "params": { "authMode": "apikey" } }
+   ```
+
+### 3) Log in with ChatGPT (browser flow)
+
+1. Start:
+   ```json
+   { "method": "account/login/start", "id": 3, "params": { "type": "chatgpt" } }
+   { "id": 3, "result": { "type": "chatgpt", "loginId": "<uuid>", "authUrl": "https://chatgpt.com/…&redirect_uri=http%3A%2F%2Flocalhost%3A<port>%2Fauth%2Fcallback" } }
+   ```
+2. Open `authUrl` in a browser; the app-server hosts the local callback.
+3. Wait for notifications:
+   ```json
+   { "method": "account/login/completed", "params": { "loginId": "<uuid>", "success": true, "error": null } }
+   { "method": "account/updated", "params": { "authMode": "chatgpt" } }
+   ```
+
+### 4) Cancel a ChatGPT login
+
+```json
+{ "method": "account/login/cancel", "id": 4, "params": { "loginId": "<uuid>" } }
+{ "method": "account/login/completed", "params": { "loginId": "<uuid>", "success": false, "error": "…" } }
+```
+
+### 5) Logout
+
+```json
+{ "method": "account/logout", "id": 5 }
+{ "id": 5, "result": {} }
+{ "method": "account/updated", "params": { "authMode": null } }
+```
+
+### 6) Rate limits (ChatGPT)
+
+```json
+{ "method": "account/rateLimits/read", "id": 6 }
+{ "id": 6, "result": { "rateLimits": { "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 }, "secondary": null } } }
+{ "method": "account/rateLimits/updated", "params": { "rateLimits": { … } } }
+```
+
+Field notes:
+- `usedPercent` is current usage within the OpenAI quota window.
+- `windowDurationMins` is the quota window length.
+- `resetsAt` is a Unix timestamp (seconds) for the next reset.
+
+### Dev notes
+
+- `codex generate-ts --out <dir>` emits v2 typings under `v2/`.
+- See [“Authentication and authorization” in the config docs](../../docs/config.md#authentication-and-authorization) for configuration knobs.
diff --git a/codex-rs/docs/codex_mcp_interface.md b/codex-rs/docs/codex_mcp_interface.md
index 5945db85..9b3a9594 100644
--- a/codex-rs/docs/codex_mcp_interface.md
+++ b/codex-rs/docs/codex_mcp_interface.md
@@ -21,7 +21,8 @@ At a glance:
   - `getUserSavedConfig`, `setDefaultModel`, `getUserAgent`, `userInfo`
   - `model/list` → enumerate available models and reasoning options
 - Auth
-  - `loginApiKey`, `loginChatGpt`, `cancelLoginChatGpt`, `logoutChatGpt`, `getAuthStatus`
+  - `account/read`, `account/login/start`, `account/login/cancel`, `account/logout`, `account/rateLimits/read`
+  - notifications: `account/login/completed`, `account/updated`, `account/rateLimits/updated`
 - Utilities
   - `gitDiffToRemote`, `execOneOffCommand`
 - Approvals (server → client requests)
@@ -113,11 +114,7 @@ The client must reply with `{ decision: "allow" | "deny" }` for each request.
 
 ## Auth helpers
 
-For ChatGPT or API‑key based auth flows, the server exposes helpers:
-
-- `loginApiKey { apiKey }`
-- `loginChatGpt` → returns `{ loginId, authUrl }`; browser completes flow; then `loginChatGptComplete` notification follows
-- `cancelLoginChatGpt { loginId }`, `logoutChatGpt`, `getAuthStatus { includeToken?, refreshToken? }`
+For the complete request/response shapes and flow examples, see the [“Auth endpoints (v2)” section in the app‑server README](../app-server/README.md#auth-endpoints-v2).
 
 ## Example: start and send a message