# How the Codex Plugin Manages Authentication and Reuses Existing Credentials

> Discover how the Codex plugin effortlessly manages authentication by reusing your existing Codex CLI credentials. Learn more about its seamless integration.

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

---

**The Codex plugin does not implement its own authentication flow; instead, it detects and reuses the authentication state of the locally installed Codex CLI through the `getCodexAuthStatus` function.**

The openai/codex-plugin-cc repository provides a code review plugin that integrates deeply with the OpenAI Codex ecosystem. Rather than maintaining separate credential storage or login mechanisms, the plugin acts as a thin wrapper around the Codex CLI's existing authentication infrastructure, automatically detecting browser sessions, API keys, and environmental configurations already established on the developer's machine.

## Detecting Codex CLI Availability and Auth State

The authentication detection process begins in the companion script at `plugins/codex/scripts/codex-companion.mjs`. This script first verifies that the `codex` binary is present on the host system before attempting to query its authentication status.

Once the CLI is confirmed available, the script imports `getCodexAuthStatus` from `plugins/codex/scripts/lib/codex.mjs`. This function instantiates a `CodexClient` with the current working directory and queries the CLI for active session information.

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

async function isReady(cwd) {
  const auth = await getCodexAuthStatus(cwd);
  console.log(`Logged in: ${auth.loggedIn}`);
  console.log(`Method: ${auth.authMethod}`);
  console.log(`Source: ${auth.source}`);
  
  // Ready if Codex is installed AND (logged in OR provider doesn't need OpenAI auth)
  return auth.loggedIn || auth.requiresOpenaiAuth === false;
}

```

## Interpreting the Authentication Status Object

The `getCodexAuthStatus` function returns a structured object containing several critical fields that determine whether the plugin can execute operations. According to the source code in `plugins/codex/scripts/lib/codex.mjs` (lines 786-842 and 848-861), this object includes:

- **`loggedIn`**: Boolean indicating whether the CLI reports a valid active session
- **`authMethod`**: String value of `"chatgpt"` (browser session), `"apiKey"` (environment variable), or `null` when the provider operates without OpenAI authentication  
- **`source`**: Origin of the credentials, either `"codex"` for standard CLI login or `"app-server"` when the plugin trusts an externally supplied API key
- **`detail`**: Human-readable description such as "API key configured (unverified)"
- **`requiresOpenaiAuth`**: Boolean indicating whether the selected provider requires OpenAI credentials versus self-hosted service operation

The companion script uses these fields to determine readiness and generate appropriate user guidance.

## App-Server Configurations and Graceful Fallbacks

When the plugin operates behind an app-server that supplies an API key, the authentication logic implements a graceful fallback mechanism. In this configuration, the `source` field reports `"app-server"` and `authMethod` returns `"apiKey"`.

Even when the underlying Codex CLI reports `loggedIn === false`, the plugin considers the authentication status **ready** because it trusts the externally supplied key. This behavior is validated in the test suite at `tests/runtime.test.mjs`, which asserts that configurations with `authMethod === "apiKey"` and `source === "app-server"` proceed without requiring manual CLI login.

The companion script implements this logic to decide whether to suggest login commands:

```javascript
const authStatus = await getCodexAuthStatus(cwd);
if (codexStatus.available && !authStatus.loggedIn && authStatus.requiresOpenaiAuth) {
  nextSteps.push(
    "If browser login is blocked, retry with `!codex login --device-auth` or `!codex login --with-api-key`."
  );
}

```

## Session Refresh and Error Propagation

The plugin handles stale sessions through a refreshable authentication flow. When encountering expired credentials, the system can re-run the auth check after triggering a Codex login refresh, allowing continued operation without manual intervention.

Error handling propagates directly from the CLI to the user. If the Codex binary returns an authentication error such as "authentication expired; run codex login", the plugin surfaces this exact message without transformation. The test fixtures in `tests/fake-codex-fixture.mjs` demonstrate this behavior through the `auth-run-fails` scenario, ensuring users receive transparent, actionable error messages.

## Summary

- **The Codex plugin delegates all authentication to the local Codex CLI**, implementing no independent credential storage or login flows.
- **`getCodexAuthStatus` in `plugins/codex/scripts/lib/codex.mjs`** creates a `CodexClient` and parses CLI output to determine session validity.
- **The auth status object** returns `loggedIn`, `authMethod`, `source`, `detail`, and `requiresOpenaiAuth` fields to guide execution decisions.
- **App-server mode** allows operation with externally supplied API keys even when the CLI reports no active session.
- **Staleness handling** supports refreshable logins, while error propagation surfaces CLI messages directly to users.

## Frequently Asked Questions

### How does the Codex plugin store API keys and credentials?

The plugin does not store API keys or credentials internally. According to the source code in `openai/codex-plugin-cc`, all authentication state resides with the Codex CLI installed on the host machine. The plugin merely queries this existing state through the `getCodexAuthStatus` function and acts as a read-only consumer of the CLI's authentication infrastructure.

### Can the plugin run without logging into the Codex CLI?

Yes, under specific conditions. If the plugin connects to an app-server that provides an API key (indicated by `source === "app-server"` and `authMethod === "apiKey"`), it operates without requiring the local Codex CLI to show `loggedIn === true`. Additionally, if the configured provider sets `requiresOpenaiAuth` to `false`, the plugin executes without any OpenAI authentication.

### What happens when the Codex CLI session expires?

When the CLI reports an expired session, the plugin surfaces the exact error message to the user, such as "authentication expired; run codex login". The test suite at `tests/runtime.test.mjs` confirms that the plugin supports refreshable authentication flows, allowing the system to re-check status after the user refreshes their CLI login without requiring a full restart of the plugin environment.

### Which source files handle the authentication detection logic?

The primary authentication logic resides in `plugins/codex/scripts/lib/codex.mjs` (specifically lines 786-861), which implements the `getCodexAuthStatus` function and `CodexClient` class. The companion script at `plugins/codex/scripts/codex-companion.mjs` consumes this status to determine readiness, while `tests/runtime.test.mjs` and `tests/fake-codex-fixture.mjs` provide test coverage for various authentication scenarios.