Skip to main content

​
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

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
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"
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
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