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

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, 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.
2. Device Code Request: It requests a device code from the authorization server using logic in 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.

The run_login_server() function in 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 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:

codex login

Configure API key authentication:

codex login --api-key

Check current authentication status:

codex status

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

Remove stored credentials:

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:

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	CLI entry point for codex login and codex logout. Parses arguments and invokes the auth manager.
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	Implements the OAuth device authorization grant flow and polling logic.
codex-rs/login/src/pkce.rs	Generates PKCE verifiers and challenges for secure OAuth exchanges.
codex-rs/core/src/config.rs	Handles serialization of the auth table to ~/.codex/config.toml.
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.
• 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.

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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}