0
# Authentication
1
2
Codex CLI supports multiple authentication methods including ChatGPT account login and OpenAI API key authentication.
3
4
## Login
5
6
```bash { .api }
7
codex login [OPTIONS] [SUBCOMMAND]
8
```
9
10
### Options
11
12
```bash { .api }
13
--api-key <API_KEY> # Login with OpenAI API key
14
```
15
16
### Subcommands
17
18
```bash { .api }
19
login status # Show current login status
20
```
21
22
## Logout
23
24
```bash { .api }
25
codex logout [OPTIONS]
26
```
27
28
## Authentication Methods
29
30
### ChatGPT Account Login (Recommended)
31
32
```bash
33
# Interactive ChatGPT login (opens browser)
34
codex login
35
```
36
37
This method:
38
- Opens a browser window for ChatGPT authentication
39
- Uses your existing ChatGPT Plus, Pro, Team, Edu, or Enterprise plan
40
- Provides the most seamless experience
41
- Automatically handles token refresh
42
43
### API Key Authentication
44
45
```bash
46
# Login with OpenAI API key
47
codex login --api-key sk-your-api-key-here
48
```
49
50
This method:
51
- Uses OpenAI API keys for usage-based billing
52
- Requires manual API key management
53
- Suitable for programmatic access
54
55
## Status Check
56
57
```bash
58
# Check current authentication status
59
codex login status
60
```
61
62
The status command shows:
63
- Current authentication method
64
- Account information
65
- Token validity
66
- Associated plan or billing information
67
68
## Examples
69
70
```bash
71
# Standard ChatGPT login
72
codex login
73
74
# Check if currently logged in
75
codex login status
76
77
# Login with API key
78
codex login --api-key sk-1234567890abcdef...
79
80
# Logout from current session
81
codex logout
82
```
83
84
## Authentication Flow
85
86
### ChatGPT Login Process
87
88
1. Run `codex login`
89
2. Browser opens to ChatGPT authentication page
90
3. Sign in to your ChatGPT account
91
4. Grant permission to Codex CLI
92
5. Return to terminal - login complete
93
94
### API Key Login Process
95
96
1. Obtain API key from OpenAI platform
97
2. Run `codex login --api-key <your-key>`
98
3. Key is securely stored locally
99
4. Ready to use Codex with API billing
100
101
## Storage and Security
102
103
- Authentication tokens are stored securely in `~/.codex/`
104
- Tokens are encrypted at rest
105
- No credentials are sent to third parties
106
- Local authentication cache for offline verification
107
108
## Troubleshooting
109
110
### Browser Login Issues
111
112
```bash
113
# If browser doesn't open automatically
114
codex login
115
# Then manually navigate to the URL shown in terminal
116
```
117
118
### Headless Environment Login
119
120
For servers or CI environments without browsers:
121
1. Run `codex login` on a machine with browser access
122
2. Copy the authentication files to the headless environment
123
3. Or use API key authentication instead
124
125
### Token Expiration
126
127
```bash
128
# If authentication expires, simply login again
129
codex login
130
131
# Check status if unsure
132
codex login status
133
```
134
135
### API Key Migration
136
137
If migrating from API key to ChatGPT account:
138
139
```bash
140
# Logout from API key
141
codex logout
142
143
# Login with ChatGPT
144
codex login
145
```
146
147
## Configuration Integration
148
149
Authentication settings can be overridden with configuration:
150
151
```bash
152
# Use different auth with config profile
153
codex --config-profile team login
154
155
# Override auth-related config
156
codex -c auth_method=api_key exec "test command"
157
```
158
159
## Environment Variables
160
161
- `OPENAI_API_KEY`: Can be used instead of login for API key authentication
162
- `CODEX_HOME`: Override location of authentication storage
163
164
## Security Best Practices
165
166
1. **Use ChatGPT login** when possible for better security
167
2. **Rotate API keys** regularly if using API key authentication
168
3. **Secure ~/.codex/** directory with appropriate file permissions
169
4. **Logout on shared systems** to prevent unauthorized access
170
5. **Use team/enterprise accounts** for organizational use cases