codex login

Authenticate with ChatGPT or provide an API key

Syntax

codex login [OPTIONS]
codex login status

Description

The login command authenticates Codex with OpenAI. You can sign in with your ChatGPT account (recommended) or provide an API key.

We recommend signing in with ChatGPT to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. Learn more about ChatGPT plans.

Usage

Sign In with ChatGPT (Recommended)

codex login

This opens your browser to sign in with your ChatGPT account.

Sign In with Device Code

If you can’t open a browser, use device code authentication:

codex login --device-auth

You’ll receive a code to enter at a URL.

Sign In with API Key

API keys require additional setup and are billed separately from ChatGPT plans.

Provide an API key from stdin:

printenv OPENAI_API_KEY | codex login --with-api-key
echo "sk-..." | codex login --with-api-key

Check Login Status

View your current authentication status:

codex login status

Options

--device-auth · boolean

Use device code authentication instead of browser-based login. Shows a code to enter at a URL.

--with-api-key · boolean

Read an API key from stdin instead of using ChatGPT authentication.

Advanced OAuth Options

--experimental_issuer · string

Custom OAuth issuer base URL. Advanced use only.

--experimental_client-id · string

Custom OAuth client ID. Advanced use only.

Examples

Standard Login Flow

# Sign in with ChatGPT (opens browser)
codex login

# Check your authentication status
codex login status

Device Code Flow

# Start device code authentication
codex login --device-auth

# Output:
# Visit https://chatgpt.com/activate
# Enter code: ABCD-1234
# Waiting for authentication...

API Key from Environment

# From environment variable
printenv OPENAI_API_KEY | codex login --with-api-key

# From file
cat api-key.txt | codex login --with-api-key

# Inline (avoid for security)
echo "sk-proj-..." | codex login --with-api-key

Verify Authentication

# Check login status
codex login status

# Sample output:
# Authenticated: Yes
# Method: ChatGPT OAuth
# Account: [e-mail]

CI/CD Authentication

For automation, use API keys:

# GitHub Actions
- name: Login to Codex
  run: |
    echo "${{ secrets.OPENAI_API_KEY }}" | codex login --with-api-key

# GitLab CI
script:
  - echo "$OPENAI_API_KEY" | codex login --with-api-key
  - codex exec "run tests"

Authentication Methods

ChatGPT OAuth (Recommended)

Pros:

• Uses your existing ChatGPT subscription
• No additional billing
• Includes plan features (Plus, Pro, Team, etc.)

How it works:

1. Run codex login
2. Browser opens to ChatGPT
3. Sign in and authorize
4. Credentials stored securely

Device Code

When to use:

• Remote servers without browser access
• Terminal-only environments
• Restricted network access

How it works:

1. Run codex login --device-auth
2. Get a device code
3. Visit URL in any browser
4. Enter code
5. Credentials stored

API Key

When to use:

• CI/CD pipelines
• Automation scripts
• Separate billing requirements

How it works:

1. Get API key from OpenAI Platform
2. Pipe to codex login --with-api-key
3. Key stored securely

API keys are billed separately on the OpenAI Platform. ChatGPT subscriptions don’t include API credits.

Credential Storage

Codex stores credentials securely using your system’s keychain:

• macOS: Keychain Access
• Linux: Secret Service API (gnome-keyring, KWallet)
• Windows: Windows Credential Manager

You can configure storage with the cli_auth_credentials_store setting in config.toml.

Troubleshooting

Browser Doesn’t Open

Use device code authentication instead:

codex login --device-auth

“Invalid API Key” Error

Ensure your API key:

• Starts with sk-proj- or sk-
• Has not expired
• Has correct permissions
• Is from OpenAI Platform

Credentials Not Persisting

Check credential storage configuration:

codex login status

Configure in ~/.codex/config.toml:

[cli_auth]
credentials_store = "keychain"  # or "file"

Related Commands

• codex logout - Remove stored credentials