# How the Codex Plugin Manages Authentication and Provider Configuration

> Learn how the Codex plugin manages authentication and provider configuration by delegating to the Codex CLI. Discover how account info and global settings create a unified status object.

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

---

**The Codex plugin delegates all authentication and provider configuration to the locally installed Codex CLI and its app-server component, querying for account information and global configuration to build a unified status object used throughout the extension.**

The openai/codex-plugin-cc repository provides a VS Code extension that integrates OpenAI's Codex CLI into the development workflow. Instead of implementing its own authentication flow, the plugin relies on the Codex CLI's app-server to verify credentials and resolve model provider settings. This architecture ensures that the plugin always respects the user's existing Codex CLI configuration and login state.

## Detecting Codex CLI Availability

Before attempting any authentication checks, the plugin verifies that the `codex` binary and its app-server component are present on the system. The `binaryAvailable` function, located in `plugins/codex/scripts/lib/process.mjs`, checks for the CLI executable.

If the binary is missing, the authentication status short-circuits immediately with `available: false`, preventing unnecessary network calls or error states. This early validation ensures that all subsequent auth logic operates only when the Codex CLI is properly installed.

## Querying the App-Server for Account and Configuration

Once the CLI is confirmed present, the plugin initializes a **CodexAppServerClient** (implemented in `plugins/codex/scripts/lib/app-server.mjs`) to communicate with the local app-server. The `getCodexAuthStatus` function in `plugins/codex/scripts/lib/codex.mjs` serves as the entry point, delegating to `getCodexAuthStatusFromClient` to perform the actual RPC calls.

The plugin sends two critical RPC requests to the app-server:

- `account/read` (with `refreshToken: false`): Returns the active account details, including the authentication type (`"chatgpt"` or `"apiKey"`)
- `config/read` (with `includeLayers: false`): Returns the global Codex configuration, specifically the `model_provider` and `model_providers` fields

Both calls are wrapped in try-catch blocks to handle network or RPC errors gracefully, converting failures into a `loggedIn: false` status with appropriate error details.

## Resolving Provider Configuration

After retrieving the raw configuration, the plugin normalizes the provider information through the `resolveProviderConfig` function in `plugins/codex/scripts/lib/codex.mjs`. This helper extracts the `model_provider` value as `providerId` and locates the matching entry in the `model_providers` array to obtain the full `providerConfig`.

The function returns a standardized object containing `providerId` and `providerConfig`, with missing values normalized to `null`. For human-readable display, the `formatProviderLabel` function converts provider identifiers into friendly labels, using a built-in mapping for common providers (`openai`, `ollama`, `lmstudio`) or falling back to the raw identifier when unknown.

## Building the Unified Auth Status

The plugin constructs a consistent status object using the `buildAuthStatus` factory function, which establishes a baseline with default fields:

```javascript
function buildAuthStatus(fields = {}) {
  return {
    available: true,
    loggedIn: false,
    detail: "not authenticated",
    source: "unknown",
    authMethod: null,
    verified: null,
    requiresOpenaiAuth: null,
    provider: null,
    ...fields
  };
}

```

The `buildAppServerAuthStatus` function then merges the account payload and resolved provider information into this baseline. It handles several distinct authentication scenarios:

- **ChatGPT login**: Sets `authMethod: "chatgpt"`, `verified: true`, and includes the user's email in the detail message
- **API-key login**: Sets `authMethod: "apiKey"` with `verified: false`
- **Local providers** (e.g., Ollama): Marks `loggedIn: true` when the provider does not require OpenAI authentication, with details indicating the specific provider
- **OpenAI-dependent providers**: Marks `loggedIn: false` when the provider requires OpenAI credentials but the user is not authenticated

All branches return the standardized object created by `buildAuthStatus`, ensuring downstream commands receive a consistent data shape regardless of the underlying authentication method.

## Public API and Usage

The plugin exports `getCodexAuthStatus(cwd, options?)` as the primary entry point for authentication checks, used by commands like `/codex:setup`. The function returns a status object with the following TypeScript interface:

```typescript
{
  available: boolean,
  loggedIn: boolean,
  detail: string,
  source: "app-server" | "availability" | "unknown",
  authMethod: "chatgpt" | "apiKey" | null,
  verified: boolean | null,
  requiresOpenaiAuth: boolean | null,
  provider: string | null
}

```

This unified structure allows the plugin to determine whether to prompt users to run `!codex login`, enable the review gate, or permit background tasks that do not require OpenAI credentials.

### Example: Checking Authentication Status

Here is a practical example of consuming the authentication API:

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

async function showAuthStatus() {
  const cwd = process.cwd();
  const status = await getCodexAuthStatus(cwd);
  console.log(`Codex available: ${status.available}`);
  console.log(`Logged in: ${status.loggedIn}`);
  console.log(`Detail: ${status.detail}`);
  console.log(`Provider: ${status.provider ?? "none"}`);
}

showAuthStatus();

```

Running this snippet produces output similar to:

```

Codex available: true
Logged in: true
Detail: ChatGPT login active for alice@example.com
Provider: openai

```

## Summary

- The Codex plugin does not implement its own authentication flow; it delegates to the Codex CLI app-server via RPC calls to `account/read` and `config/read`.
- Authentication status is determined by querying the local app-server through the `CodexAppServerClient` class in `plugins/codex/scripts/lib/app-server.mjs`.
- Provider configuration is normalized through `resolveProviderConfig`, which extracts `model_provider` and matching entries from `model_providers`.
- The `buildAuthStatus` and `buildAppServerAuthStatus` functions create a standardized status object used across the plugin to handle ChatGPT logins, API keys, and local providers like Ollama.
- The public `getCodexAuthStatus` API returns a consistent object containing `available`, `loggedIn`, `authMethod`, `provider`, and other fields required by VS Code commands.

## Frequently Asked Questions

### How does the Codex plugin verify that the user is logged in?

The plugin sends an RPC request to the local Codex app-server using the `account/read` method. This returns the current account type (`chatgpt` or `apiKey`) and authentication state. If the app-server is unreachable or returns an error, the plugin sets `loggedIn: false` and provides an appropriate error detail message.

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

If the `binaryAvailable` check in `plugins/codex/scripts/lib/process.mjs` fails to locate the `codex` executable, the authentication status immediately returns `available: false`. This short-circuit prevents unnecessary network requests and ensures the plugin only attempts app-server communication when the CLI is properly installed on the system.

### How does the plugin handle different model providers like Ollama or LM Studio?

The plugin reads the global configuration via the `config/read` RPC call and passes the result to `resolveProviderConfig`. This function extracts the configured `model_provider` and looks up the corresponding entry in `model_providers`. For display purposes, `formatProviderLabel` maps provider IDs to human-readable names. When a local provider like Ollama is configured and does not require OpenAI authentication, the plugin sets `loggedIn: true` even without OpenAI credentials.

### Where is the authentication logic implemented in the source code?

The core authentication logic resides in `plugins/codex/scripts/lib/codex.mjs`, which contains the `getCodexAuthStatus`, `resolveProviderConfig`, `buildAuthStatus`, and `buildAppServerAuthStatus` functions. The `CodexAppServerClient` class used for RPC communication is defined in `plugins/codex/scripts/lib/app-server.mjs`, while binary availability checks are handled in `plugins/codex/scripts/lib/process.mjs`.