# How to Manage Login Credentials for Codex CLI: OAuth and API Key Authentication

> Learn to manage Codex CLI login credentials using OAuth device flow and API keys. Securely authenticate with codex login and remove tokens with codex logout.

- Repository: [OpenAI/codex](https://github.com/openai/codex)
- Tags: how-to-guide
- Published: 2026-03-06

---

**The Codex CLI stores authentication tokens in `~/.codex/config.toml` and provides `codex login` for OAuth device flow, `codex login --api-key` for API keys, and `codex logout` to clear credentials.**

Managing login credentials for the Codex CLI involves understanding how the OpenAI Codex repository handles authentication persistence and secure storage. The CLI supports both OAuth device-code authentication and direct API key storage, writing all session data to a local TOML configuration file that the auth manager reads on every invocation.

## Where Codex CLI Stores Credentials

### The Configuration File

The CLI persists all authentication state in the user’s home directory at `~/.codex/config.toml`. This file contains an `[auth]` table that stores either OAuth tokens or API key material depending on the chosen method.

According to the implementation in [`codex-rs/core/src/config.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/config.rs), the configuration struct handles serialization and deserialization of these credentials. When using OAuth, the file stores `access_token`, `refresh_token`, and `expires_at` fields. For API key authentication, it stores the key in `auth.api_key`.

## Authentication Methods

### OAuth Device Code Flow (Default)

The default authentication method uses the OAuth 2.0 device authorization grant with **PKCE** (Proof Key for Code Exchange). When you run `codex login`, the CLI executes the following sequence implemented across several source files:

1. **PKCE Generation**: The CLI generates a verifier and challenge in [`codex-rs/login/src/pkce.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/pkce.rs).
2. **Device Code Request**: It requests a device code from the authorization server using logic in [`codex-rs/login/src/device_code_auth.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/device_code_auth.rs).
3. **User Authorization**: It opens a browser for the user to authorize the device.
4. **Token Exchange**: Upon completion, it exchanges the device code for access and refresh tokens.
5. **Persistence**: It writes the tokens to `~/.codex/config.toml` via the auth manager in [`codex-rs/login/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/lib.rs).

The `run_login_server()` function in [`codex-rs/login/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/lib.rs) orchestrates this entire flow.

### API Key Authentication

For headless environments or automated workflows, the CLI supports direct API key authentication. The command `codex login --api-key` prompts for a key and stores it in the configuration file.

The `login_with_api_key()` function in [`codex-rs/login/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/lib.rs) handles this storage, placing the key in the `auth.api_key` field. When an API key is present, the CLI skips the OAuth flow entirely and uses the key for all requests.

## CLI Commands for Credential Management

The Codex CLI provides specific commands for managing the authentication lifecycle:

**Initiate OAuth login:**

```bash
codex login

```

**Configure API key authentication:**

```bash
codex login --api-key

```

**Check current authentication status:**

```bash
codex status

```

This displays whether you're authenticated via OAuth (with expiry time) or API key.

**Remove stored credentials:**

```bash
codex logout

```

This command removes the `[auth]` section from `~/.codex/config.toml`, forcing re-authentication on the next command.

## Programmatic Access

If you are building a tool that needs to use the same authentication mechanisms, the `codex-login` crate exposes the underlying Rust API:

```rust
use codex_login::{run_login_server, ServerOptions};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Start the login server with default options
    let opts = ServerOptions::default();
    let auth = run_login_server(opts).await?;
    
    println!("Access token: {}", auth.access_token);
    // The auth struct also contains refresh_token and expiry
    Ok(())
}

```

This mirrors the behavior of the `codex login` command and handles PKCE generation, device code polling, and token storage automatically.

## Key Implementation Files

Understanding these source files helps when debugging authentication issues or extending the CLI:

| File | Role |
|------|------|
| [`codex-rs/cli/src/login.rs`](https://github.com/openai/codex/blob/main/codex-rs/cli/src/login.rs) | CLI entry point for `codex login` and `codex logout`. Parses arguments and invokes the auth manager. |
| [`codex-rs/login/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/lib.rs) | Core authentication logic including `run_login_server`, `login_with_api_key`, and token refresh handling. |
| [`codex-rs/login/src/device_code_auth.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/device_code_auth.rs) | Implements the OAuth device authorization grant flow and polling logic. |
| [`codex-rs/login/src/pkce.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/pkce.rs) | Generates PKCE verifiers and challenges for secure OAuth exchanges. |
| [`codex-rs/core/src/config.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/config.rs) | Handles serialization of the `auth` table to `~/.codex/config.toml`. |
| [`codex-rs/tui/src/onboarding/auth.rs`](https://github.com/openai/codex/blob/main/codex-rs/tui/src/onboarding/auth.rs) | UI layer that displays login status and prompts in the terminal interface. |

## Summary

- The Codex CLI stores credentials in **`~/.codex/config.toml`** under the `[auth]` table.
- **OAuth device flow** is the default, using PKCE and automatic token refresh implemented in [`codex-rs/login/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/lib.rs).
- **API key authentication** is available via `codex login --api-key` for headless environments.
- Use **`codex logout`** to clear credentials and **`codex status`** to verify current authentication state.
- The authentication system is implemented across the `codex-rs/login` and `codex-rs/core` crates, with the CLI interface in [`codex-rs/cli/src/login.rs`](https://github.com/openai/codex/blob/main/codex-rs/cli/src/login.rs).

## Frequently Asked Questions

### Where does the Codex CLI store my API key or OAuth tokens?

The CLI persists all authentication material in a TOML file at `~/.codex/config.toml` (located in your home directory). This file contains an `[auth]` section that stores either an `api_key` string for API key authentication, or `access_token`, `refresh_token`, and `expires_at` fields for OAuth sessions. The serialization logic is handled in [`codex-rs/core/src/config.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/config.rs).

### How do I switch from API key authentication back to OAuth?

First, run `codex logout` to remove the existing API key from the configuration file. Then execute `codex login` without any flags to initiate the OAuth device code flow. The CLI will launch the browser-based authorization process and overwrite the `[auth]` section with new OAuth tokens upon completion.

### Does the Codex CLI automatically refresh expired OAuth tokens?

Yes. According to the implementation in [`codex-rs/login/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/login/src/lib.rs), the authentication manager checks token expiry before making API requests. If the access token has expired, it automatically uses the stored refresh token to obtain a new access token and updates `~/.codex/config.toml` with the renewed credentials.

### Can I use the Codex CLI in a CI/CD pipeline or other automated environment?

Yes, but you should use API key authentication rather than OAuth for automated environments. Run `codex login --api-key` locally to configure your key, then copy the `~/.codex/config.toml` file to your CI environment's home directory. The OAuth flow requires browser interaction and a local HTTP server, making it unsuitable for headless automation.