Authentication

Codex CLI supports multiple authentication methods including ChatGPT account login and OpenAI API key authentication.

Login

codex login [OPTIONS] [SUBCOMMAND]

Options

--api-key <API_KEY>    # Login with OpenAI API key

Subcommands

login status           # Show current login status

Logout

codex logout [OPTIONS]

Authentication Methods

ChatGPT Account Login (Recommended)

# Interactive ChatGPT login (opens browser)
codex login

This method:

• Opens a browser window for ChatGPT authentication
• Uses your existing ChatGPT Plus, Pro, Team, Edu, or Enterprise plan
• Provides the most seamless experience
• Automatically handles token refresh

API Key Authentication

# Login with OpenAI API key
codex login --api-key sk-your-api-key-here

This method:

• Uses OpenAI API keys for usage-based billing
• Requires manual API key management
• Suitable for programmatic access

Status Check

# Check current authentication status
codex login status

The status command shows:

• Current authentication method
• Account information
• Token validity
• Associated plan or billing information

Examples

# Standard ChatGPT login
codex login

# Check if currently logged in
codex login status

# Login with API key
codex login --api-key sk-1234567890abcdef...

# Logout from current session
codex logout

Authentication Flow

ChatGPT Login Process

1. Run codex login
2. Browser opens to ChatGPT authentication page
3. Sign in to your ChatGPT account
4. Grant permission to Codex CLI
5. Return to terminal - login complete

API Key Login Process

1. Obtain API key from OpenAI platform
2. Run codex login --api-key <your-key>
3. Key is securely stored locally
4. Ready to use Codex with API billing

Storage and Security

• Authentication tokens are stored securely in ~/.codex/
• Tokens are encrypted at rest
• No credentials are sent to third parties
• Local authentication cache for offline verification

Troubleshooting

Browser Login Issues

# If browser doesn't open automatically
codex login
# Then manually navigate to the URL shown in terminal

Headless Environment Login

For servers or CI environments without browsers:

1. Run codex login on a machine with browser access
2. Copy the authentication files to the headless environment
3. Or use API key authentication instead

Token Expiration

# If authentication expires, simply login again
codex login

# Check status if unsure
codex login status

API Key Migration

If migrating from API key to ChatGPT account:

# Logout from API key
codex logout

# Login with ChatGPT
codex login

Configuration Integration

Authentication settings can be overridden with configuration:

# Use different auth with config profile
codex --config-profile team login

# Override auth-related config
codex -c auth_method=api_key exec "test command"

Environment Variables

• OPENAI_API_KEY: Can be used instead of login for API key authentication
• CODEX_HOME: Override location of authentication storage

Security Best Practices

1. Use ChatGPT login when possible for better security
2. Rotate API keys regularly if using API key authentication
3. Secure ~/.codex/ directory with appropriate file permissions
4. Logout on shared systems to prevent unauthorized access
5. Use team/enterprise accounts for organizational use cases