# How the Codex Plugin Handles Authentication and Provider Configuration

> Discover how the Codex plugin manages authentication and provider configuration by leveraging the Codex CLI and app-server for unified status and authorization. Learn more.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-28

---

**The Codex plugin delegates all authentication concerns to the locally-installed Codex CLI and its app-server, querying for account information and global configuration to build a unified status object that drives the plugin's authorization decisions.**

The openai/codex-plugin-cc repository implements a VS Code extension that integrates OpenAI's Codex CLI into the editor. Rather than implementing its own authentication flow or credential storage, the plugin relies entirely on the locally installed Codex CLI and its app-server component to manage credentials and provider settings.

## Detecting Codex CLI Availability

Before attempting any authentication checks, the plugin verifies that the `codex` binary and its app-server are present. In `plugins/codex/scripts/lib/process.mjs`, the `binaryAvailable` function checks for the CLI on disk. If the binary is missing, the auth status short-circuits immediately with `available: false`, preventing further RPC calls to a non-existent server.

## Querying the App-Server for Account and Configuration

The core authentication logic resides in `plugins/codex/scripts/lib/codex.mjs`. The exported `getCodexAuthStatus` function instantiates a **CodexAppServerClient** (defined in `plugins/codex/scripts/lib/app-server.mjs`) and delegates to `getCodexAuthStatusFromClient`. This helper issues two synchronous RPC calls to the local app-server:

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

Both calls are wrapped in `try / catch` blocks. Network failures or RPC errors are transformed into a `loggedIn: false` status, ensuring the plugin degrades gracefully when the app-server is unreachable.

## Resolving Provider Configuration

Raw configuration data from the app-server requires normalization before the plugin can use it to determine authorization requirements.

### Normalizing Provider Information

The `resolveProviderConfig` function in `plugins/codex/scripts/lib/codex.mjs` processes the config response:

- Extracts `model_provider` as `providerId`
- Looks up the matching entry in the `model_providers` array as `providerConfig`
- Returns an object `{ providerId, providerConfig }` where missing values become `null`

### Formatting Provider Labels

The `formatProviderLabel` helper converts provider identifiers into human-readable strings. It maintains a built-in mapping for known providers including `openai`, `ollama`, and `lmstudio`, falling back to the raw ID string for custom or unknown configurations.

## Building the Unified Auth Status

The plugin standardizes authentication state through two builder functions in `plugins/codex/scripts/lib/codex.mjs`, ensuring consistent data structures for downstream commands.

### The Status Object Structure

`buildAuthStatus` creates a baseline object with fields used throughout the plugin:

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

```

### Authentication Method Mapping

`buildAppServerAuthStatus` combines the account payload and resolved provider info into the final status object:

- **ChatGPT login**: Sets `authMethod: "chatgpt"`, `verified: true`, and includes the user's email in the `detail` field
- **API key login**: Sets `authMethod: "apiKey"` with `verified: false`
- **Local providers** (e.g., Ollama): Sets `loggedIn: true` with a detail message indicating the provider is configured and does not require OpenAI authentication
- **OpenAI-dependent providers**: Sets `loggedIn: false` when OpenAI authentication is required but missing, with an appropriate detail message

All branches return the standardized object created by `buildAuthStatus`, exposing a consistent shape to callers regardless of the underlying authentication method.

## Public API and Usage

The plugin exports `getCodexAuthStatus(cwd, options?)` as the primary entry point used by commands like `/codex:setup`. The function returns an 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 status object determines whether to prompt the user to run `!codex login`, enable the review gate, or allow background tasks that do not require OpenAI credentials.

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

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

```

## Summary

- The plugin delegates authentication to the Codex CLI app-server rather than implementing its own credential flow or storage
- **Availability checks** in `process.mjs` prevent calls to missing binaries and return `available: false` immediately
- **RPC calls** to `account/read` and `config/read` retrieve credentials and provider settings from the local app-server
- **Provider resolution** via `resolveProviderConfig` normalizes provider IDs and configuration objects
- **Status standardization** through `buildAuthStatus` ensures consistent output for downstream commands regardless of whether the user authenticated via ChatGPT or API key

## Frequently Asked Questions

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

No. According to the openai/codex-plugin-cc source code, the plugin does not implement its own authentication flow or store credentials. It delegates all auth concerns to the locally-installed Codex CLI and queries the app-server for current account information via the `account/read` RPC method.

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

If `binaryAvailable` in `plugins/codex/scripts/lib/process.mjs` detects that the `codex` binary is missing, `getCodexAuthStatus` returns immediately with `available: false` and `loggedIn: false`, short-circuiting further authentication checks and preventing RPC errors.

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

The plugin reads the `model_provider` and `model_providers` fields from the app-server configuration via the `config/read` RPC call. It supports built-in labels for `openai`, `ollama`, and `lmstudio` through `formatProviderLabel`, and can distinguish between providers that require OpenAI authentication versus local instances that operate without it.

### What is the difference between ChatGPT and API key authentication methods in the status object?

ChatGPT login sets `authMethod: "chatgpt"` with `verified: true` and includes the user's email address in the detail field, while API key login sets `authMethod: "apiKey"` with `verified: false`. This verification status affects how downstream commands interpret the authentication context and whether they prompt for additional login steps.