Authentication

Sign in with ChatGPT or configure API key authentication for Codex CLI

Authentication

Codex CLI supports multiple authentication methods to suit your workflow. You can sign in with your ChatGPT account (recommended) or use an OpenAI API key.

Authentication methods

Codex CLI offers three authentication methods:

1. ChatGPT login (recommended): Sign in with your ChatGPT Plus, Pro, Team, Edu, or Enterprise account
2. Device code flow: For remote or headless machines
3. API key: For users with OpenAI API access

We recommend using ChatGPT login to use Codex as part of your ChatGPT plan. Learn more about what’s included.

Sign in with ChatGPT

This is the recommended authentication method. It allows you to use Codex with your ChatGPT Plus, Pro, Team, Edu, or Enterprise plan.

1. Run the login command

   Start the authentication process:

   codex login
   

   Or if you’re running Codex for the first time:

   codex
   

   Then select Sign in with ChatGPT from the prompt.

2. Authenticate in browser

   Codex will:

   1. Start a local login server on http://localhost (random port)
   2. Automatically open your browser to the authentication page
   3. Prompt you to sign in with your ChatGPT credentials

   You’ll see output like:

   Starting local login server on http://localhost:3000.
   If your browser did not open, navigate to this URL to authenticate:
   
   https://auth.openai.com/authorize?...
   
   On a remote or headless machine? Use `codex login --device-auth` instead.
   
3. Complete authentication

   After signing in through the browser:

   1. Authorize Codex to access your ChatGPT account
   2. You’ll be redirected back to a success page
   3. Return to your terminal

   You’ll see:

   Successfully logged in
   
4. Start using Codex

   You’re now authenticated and can start using Codex:

   codex "explain this codebase"
   

Device code authentication

Use device code flow when you’re on a remote machine, in SSH, or in a headless environment where opening a browser isn’t possible.

1. Run device code login

   Start the device code authentication flow:

   codex login --device-auth
   
2. Open the URL on another device

   Codex will display a URL and a code:

   Visit https://auth.openai.com/activate
   Enter code: ABCD-EFGH
   

   Open this URL on any device with a browser (your phone, laptop, etc.).

3. Enter the code

   On the browser:

   1. Navigate to the URL
   2. Enter the displayed code
   3. Sign in with your ChatGPT credentials
   4. Authorize the application
4. Wait for confirmation

   Return to your terminal. Once you complete authentication in the browser, you’ll see:

   Successfully logged in
   

   You can now use Codex on the remote machine.

API key authentication

If you have an OpenAI API key, you can authenticate using the API key method. This requires additional setup but gives you direct API access.

Using an API key with Codex will incur costs based on your API usage. ChatGPT login is included in your ChatGPT plan at no additional cost.

Using the login command

1. Pipe your API key to the login command

   Codex accepts API keys via stdin for security:

   printenv OPENAI_API_KEY | codex login --with-api-key
   

   Or:

   echo "sk-proj-..." | codex login --with-api-key
   

   For security reasons, Codex does not accept API keys as command-line arguments. Always pipe the key via stdin.

2. Verify authentication

   After successful authentication, you’ll see:

   Reading API key from stdin...
   Successfully logged in
   

Using environment variables

Alternatively, you can set your API key as an environment variable:

1. Export the API key

   Set the OPENAI_API_KEY environment variable:

   export OPENAI_API_KEY="sk-proj-..."
   

   This sets the key only for your current terminal session. To make it permanent, add the export line to your shell configuration file (e.g., ~/.zshrc, ~/.bashrc).

2. Run Codex

   Run Codex normally. It will automatically use the environment variable:

   codex "explain this code"
   

Using a .env file

For project-specific API keys, create a .env file in your project root:

1. Create a .env file

   Create a .env file in your project directory:

   .env

   OPENAI_API_KEY=sk-proj-...
   
2. Run Codex in the project directory

   Codex will automatically load the API key from the .env file:

   codex "refactor this function"
   

   The CLI automatically loads environment variables from .env using dotenv/config.

Security best practice: Never commit your .env file to version control. Add it to .gitignore:

.gitignore

.env

Using other AI providers

Codex supports other AI providers that implement the OpenAI Chat Completions API. Use the --provider flag or configure it in your config file.

Supported providers

• openai (default)
• openrouter
• azure
• gemini
• ollama
• mistral
• deepseek
• xai
• groq
• arceeai
• Any provider compatible with the OpenAI API

Configure a custom provider

1. Set the API key for your provider

   Export the API key for your chosen provider:

   export AZURE_OPENAI_API_KEY="your-azure-key"
   

   Or for a custom provider:

   export MYPROVIDER_API_KEY="your-key"
   export MYPROVIDER_BASE_URL="https://api.myprovider.com/v1"
   
2. Run Codex with the provider flag

   Specify the provider when running Codex:

   codex --provider azure "explain this code"
   

   Or configure it permanently in ~/.codex/config.yaml (see Configuration).

Check login status

To verify your current authentication status:

codex login status

This will show:

• ChatGPT login: Logged in using ChatGPT
• API key: Logged in using an API key - sk-proj-***ABCDE (key is partially masked)
• Not logged in: Not logged in

Logout

To remove stored authentication credentials:

codex logout

You’ll see:

Successfully logged out

Your credentials are removed from ~/.codex/. You’ll need to authenticate again to use Codex.

Troubleshooting

Browser doesn't open during login

If the browser doesn’t open automatically:

1. Copy the URL displayed in the terminal
2. Manually paste it into your browser
3. Complete authentication

Or use device code authentication:

codex login --device-auth

API key not working

If you’re using an API key and Codex isn’t authenticating:

1. Verify the key is correct:

   printenv OPENAI_API_KEY
   

2. Check that the key hasn’t expired on the OpenAI platform

3. Ensure you’re using the correct provider:

   codex --provider openai "test"
   

Permission denied errors

If you see permission errors with stored credentials:

1. Check the permissions on ~/.codex/:

   ls -la ~/.codex/
   

2. Fix permissions if needed:

   chmod 700 ~/.codex/
   chmod 600 ~/.codex/auth.json
   

Error on remote/SSH sessions

If ChatGPT login fails on a remote machine:

Use device code authentication instead:

codex login --device-auth

This works on headless systems and in SSH sessions.

Next steps

Quickstart guide

Run your first commands with Codex

Configuration

Customize Codex with config files

CLI reference

Explore all available commands

Security model

Learn about sandboxing and permissions