# How `getCodexAuthStatus` Handles Authentication in the Codex Plugin

> Learn how getCodexAuthStatus in the Codex plugin checks CLI availability, connects to the app server, and queries data to manage authentication. Understand your Codex integration.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-08-03

---

**The `getCodexAuthStatus` function in the Codex plugin determines authentication state by checking CLI availability, connecting to the Codex app-server, and querying account and configuration data via RPC calls.**

The **Codex plugin** (from the openai/codex-plugin-cc repository) provides a robust mechanism for detecting whether a user is authenticated with OpenAI's Codex service. This article explores the complete authentication flow implemented in `plugins/codex/scripts/lib/codex.mjs`, including binary detection, app-server communication, and status normalization.

## Authentication Pipeline Overview

The `getCodexAuthStatus` function implements a **four-stage pipeline** that gracefully degrades when components are missing. Understanding this flow is essential for debugging auth issues or extending the plugin.

### Stage 1: Verify Codex Binary Availability

Before attempting any network operations, `getCodexAuthStatus` calls `getCodexAvailability` (lines 886-904) to confirm the `codex` CLI is installed and its app-server runtime is accessible.

```javascript
// From plugins/codex/scripts/lib/codex.mjs
if (!await getCodexAvailability(cwd)) {
  return buildAuthStatus({ available: false, detail: "Codex CLI not found" });
}

```

If the binary check fails, the function returns immediately with `available: false`, avoiding unnecessary connection attempts.

### Stage 2: Establish App-Server Connection

When the binary is present, `getCodexAuthStatus` instantiates `CodexAppServerClient` and calls `.connect()` (lines 1419-1425). The client defaults to re-using an existing broker if one is already running, reducing startup overhead.

```javascript
const client = await CodexAppServerClient.connect(cwd);

```

This connection is the gateway for all subsequent RPC calls to the Codex service.

### Stage 3: Query Account and Configuration

The helper function `getCodexAuthStatusFromClient` (approximately lines 869-876) makes two parallel RPC calls:

- **`account/read`** — with `refreshToken: false` to avoid side effects, returns the current account (ChatGPT login or API key)
- **`config/read`** — returns provider configuration including authentication requirements

```javascript
// Conceptual flow based on implementation
const [account, config] = await Promise.all([
  client.request("account/read", { refreshToken: false }),
  client.request("config/read")
]);

```

These responses feed into `buildAppServerAuthStatus` (lines 817-866), which produces a normalized authentication object.

### Stage 4: Build Unified Status Object

The `buildAppServerAuthStatus` function interprets account types to populate these fields:

| Account Type | `authMethod` | `verified` | `loggedIn` |
|-------------|-------------|-----------|-----------|
| ChatGPT login (`type: "chatgpt"`) | `"chatgpt"` | `true` | `true` |
| API key (`type: "apiKey"`) | `"apiKey"` | `false` | `true` |
| Provider without OpenAI auth requirement | provider-specific | varies | `true` |
| No valid credentials | — | — | `false` |

## Error Handling and Fallback Behavior

When RPC calls fail or the app-server is unreachable, `getCodexAuthStatusFromClient` falls back to `buildAuthStatus` (lines 780-792), returning a generic **not logged-in** state:

```javascript
return buildAuthStatus({
  available: true,  // Binary exists even if server unreachable
  loggedIn: false,
  detail: "Unable to verify authentication status"
});

```

This ensures callers always receive a predictable object shape regardless of failure mode.

## Practical Code Examples

### Check Authentication Status

```javascript
import { getCodexAuthStatus } from "./lib/codex.mjs";

async function checkAuth(cwd) {
  const status = await getCodexAuthStatus(cwd);
  
  console.log("Available:", status.available);
  console.log("Logged in:", status.loggedIn);
  console.log("Method:", status.authMethod);
  console.log("Provider:", status.provider);
}

checkAuth(process.cwd());

```

### Handle Missing CLI Installation

```javascript
const status = await getCodexAuthStatus(cwd);

if (!status.available) {
  console.error("Codex CLI missing — install with:");
  console.error("  npm install -g @openai/codex");
  process.exit(1);
}

```

### Conditional Login Prompts

```javascript
if (status.requiresOpenaiAuth && !status.loggedIn) {
  console.log("OpenAI authentication required. Run /codex:login");
} else if (status.authMethod === "apiKey" && !status.verified) {
  console.log("API key present but unverified — check your key");
}

```

## Key Implementation Files

| File | Responsibility |
|------|--------------|
| `plugins/codex/scripts/lib/codex.mjs` | Core authentication logic: `getCodexAuthStatus`, `buildAppServerAuthStatus`, `buildAuthStatus` |
| `plugins/codex/scripts/lib/app-server.mjs` | `CodexAppServerClient` class, RPC transport layer |
| `plugins/codex/scripts/lib/process.mjs` | `binaryAvailable` helper for CLI detection |
| [`plugins/codex/scripts/commands/status.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/commands/status.md) | User-facing command invoking `getCodexAuthStatus` |

## Summary

- **`getCodexAuthStatus`** validates the Codex CLI binary before attempting connections
- The function uses **`CodexAppServerClient.connect`** to establish RPC communication
- Two queries — **`account/read`** and **`config/read`** — determine the authentication state
- **`buildAppServerAuthStatus`** normalizes responses into a consistent object shape with fields like `authMethod`, `verified`, and `requiresOpenaiAuth`
- Graceful fallback to **`buildAuthStatus`** ensures predictable behavior during failures

## Frequently Asked Questions

### What does `getCodexAuthStatus` return when Codex isn't installed?

It returns an object with `available: false` and a `detail` string explaining that the Codex CLI was not found. This happens at the initial `getCodexAvailability` check before any connection attempts.

### How does the plugin distinguish between ChatGPT login and API key authentication?

The `account/read` RPC returns a `type` field. When `type: "chatgpt"`, the plugin sets `authMethod: "chatgpt"` and `verified: true`. When `type: "apiKey"`, it sets `authMethod: "apiKey"` and `verified: false` since API keys aren't pre-validated.

### Why does `verified` differ between authentication methods?

ChatGPT logins are verified through OpenAI's OAuth flow at login time, so the plugin trusts `verified: true`. API keys are stored locally without server-side validation during status checks, so they remain `verified: false` until actually used.

### Can `getCodexAuthStatus` trigger token refresh or re-authentication?

No — the `account/read` call explicitly passes `refreshToken: false` to avoid side effects. Status checks are read-only operations that won't modify authentication state or trigger login flows.