# How Codex Authentication Is Handled by the Plugin: A Complete Technical Guide

> Learn how the Codex plugin handles authentication by reusing your local Codex CLI and app server login status and provider config through RPC calls. Get the complete technical guide for openai/codex-plugin-cc.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-04

---

**The Codex plugin does not implement its own authentication flow; instead, it transparently reuses the authentication state of the locally installed Codex CLI and app-server by querying RPC endpoints to determine login status and provider configuration.**

The openai/codex-plugin-cc repository provides a VS Code extension that integrates OpenAI's Codex CLI into the editor. Understanding how Codex authentication works within this plugin is essential for developers configuring automated code reviews or setup commands, as the plugin acts as a thin client that delegates all credential management to the underlying Codex binary.

## Why the Plugin Delegates to the Codex CLI

Rather than managing API keys or OAuth tokens internally, the plugin implements a **transparent pass-through** architecture. This design ensures that any authentication method supported by the Codex CLI—whether ChatGPT login or API key—works immediately within the plugin without duplication.

### Verifying Binary Availability

Before attempting any authentication query, the plugin validates that the `codex` binary is present and that the app-server can be launched. The `getCodexAvailability` function in `plugins/codex/scripts/lib/codex.mjs` executes `codex app-server --help` to confirm the local installation is functional.

## How the Plugin Queries Authentication State

Once the binary is confirmed, the plugin establishes a connection to the **app-server** and issues remote procedure calls (RPC) to inspect the current session.

### Establishing the App-Server Connection

The plugin creates a `CodexAppServerClient` instance, implemented in `plugins/codex/scripts/lib/app-server.mjs`, and invokes `CodexAppServerClient.connect` to initiate communication over the RPC protocol. This client serves as the bridge between the VS Code extension and the local Codex service.

### RPC Calls to Fetch Account Data

The client issues two critical RPC calls to determine authentication status:

- **`account/read`** (with `refreshToken:false`): Retrieves whether the user is logged in and identifies the authentication method (`chatgpt` or `apiKey`).
- **`config/read`**: Inspects the current provider configuration to determine if OpenAI authentication is required.

### Normalizing the Auth Status

Raw RPC responses are normalized by the `buildAuthStatus` function in `plugins/codex/scripts/lib/codex.mjs`. This function constructs a standardized object consumed by all plugin commands.

## The Authentication Status Object

The normalized status object contains the following fields:

- **`available`**: Boolean indicating whether the Codex binary and app-server are reachable.
- **`loggedIn`**: Boolean indicating whether an active login session exists.
- **`authMethod`**: String value of `"chatgpt"` or `"apiKey"` (or `null` when not required).
- **`source`**: String indicating the data source (`"app-server"` or `"availability"` when the binary is missing).
- **`detail`**: Human-readable description (e.g., "ChatGPT login active for user@example.com").
- **`requiresOpenaiAuth`**: Boolean indicating whether the selected provider requires OpenAI authentication.
- **`provider`**: The provider identifier (e.g., `openai`).

## Handling Authentication in Commands

All command implementations—including `/codex:setup`, `/codex:review`, and others—call `getCodexAuthStatus` to determine whether to proceed, prompt for login, or allow API-key-only operation.

For example, when running setup:

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

export async function runSetup(cwd) {
  const auth = await getCodexAuthStatus(cwd);
  if (!auth.available) {
    // suggest installing Codex
  } else if (!auth.loggedIn) {
    // advise the user to run `!codex login`
  } else {
    // ready to go
  }
}

```

### Error Handling for Expired Sessions

If RPC calls fail—for instance, when a session expires—the plugin catches the error and returns a status with `loggedIn:false` and a descriptive `detail` message such as "authentication expired; run codex login". This allows commands to surface actionable guidance to users.

## Summary

- The plugin does not implement custom authentication; it delegates to the local Codex CLI.
- Authentication status is determined by querying the app-server via RPC calls (`account/read` and `config/read`).
- The `buildAuthStatus` function in `codex.mjs` normalizes responses into a standard object with fields like `loggedIn`, `authMethod`, and `requiresOpenaiAuth`.
- All commands check `getCodexAuthStatus` to decide whether to execute or prompt for login.
- Expired sessions are handled gracefully with user-friendly error messages directing users to run `codex login`.

## Frequently Asked Questions

### Does the Codex plugin store API keys or credentials?

No. The plugin does not store any credentials. It relies entirely on the authentication state managed by the locally installed Codex CLI. When you run `codex login` in your terminal, that session becomes available to the plugin through the app-server RPC interface.

### What happens if the Codex CLI is not installed?

If the `codex` binary is missing, the `getCodexAvailability` function returns `available:false`. All subsequent authentication checks will indicate that the binary is unreachable, and commands will prompt you to install the Codex CLI before proceeding.

### How does the plugin handle different authentication methods like ChatGPT vs. API key?

The plugin queries the `account/read` RPC endpoint to determine the active `authMethod` (`"chatgpt"` or `"apiKey"`). It then checks `config/read` to see if the current provider requires OpenAI authentication. This allows the plugin to support both methods transparently without requiring configuration changes in VS Code.

### Where is the authentication logic tested?

The authentication status parsing and error handling are validated in `tests/runtime.test.mjs`, which confirms that the plugin correctly interprets various scenarios including logged-in states, API-key-only providers, and missing or expired authentication.