0
# Authentication & Session Management
1
2
Complete user authentication system for Webull API access, including email/phone login, Multi-Factor Authentication (MFA), security questions, and session management with token refresh capabilities.
3
4
## Capabilities
5
6
### User Login
7
8
Primary authentication method supporting both email and phone number login with password. Webull requires MFA for all accounts since 2020.
9
10
```python { .api }
11
def login(self, username='', password='', device_name='', mfa='', question_id='', question_answer='', save_token=False, token_path=None):
12
"""
13
Log in to Webull account with email/phone and password.
14
15
Parameters:
16
- username (str): Email address or phone number in format +[country_code]-[number]
17
- password (str): Account password
18
- device_name (str, optional): Device identifier for login
19
- mfa (str, optional): Multi-factor authentication code
20
- question_id (str, optional): Security question ID if required
21
- question_answer (str, optional): Answer to security question
22
- save_token (bool, optional): Whether to save authentication token to file
23
- token_path (str, optional): Custom path for saving token file
24
25
Returns:
26
dict: Login response containing access tokens and session info
27
28
Raises:
29
ValueError: If username or password is missing
30
"""
31
```
32
33
Usage example:
34
35
```python
36
from webull import webull
37
38
wb = webull()
39
40
# Email login
41
response = wb.login('user@example.com', 'password123')
42
43
# Phone login (must include country code)
44
response = wb.login('+1-5551234567', 'password123')
45
46
# Login with token saving
47
response = wb.login('user@example.com', 'password123', save_token=True)
48
```
49
50
### Multi-Factor Authentication
51
52
Handle MFA verification required by Webull for account security.
53
54
```python { .api }
55
def get_mfa(self, username=''):
56
"""
57
Request MFA code to be sent to user's registered method.
58
59
Parameters:
60
- username (str): Email or phone number used for login
61
62
Returns:
63
dict: Response indicating MFA code delivery status
64
"""
65
66
def check_mfa(self, username='', mfa=''):
67
"""
68
Verify MFA code received by user.
69
70
Parameters:
71
- username (str): Email or phone number used for login
72
- mfa (str): Multi-factor authentication code
73
74
Returns:
75
dict: Verification result
76
"""
77
```
78
79
Usage example:
80
81
```python
82
# Request MFA code
83
wb.get_mfa('user@example.com')
84
85
# User receives code via SMS/email
86
mfa_code = input("Enter MFA code: ")
87
88
# Verify MFA code
89
result = wb.check_mfa('user@example.com', mfa_code)
90
```
91
92
### Security Questions
93
94
Handle additional security verification when required by Webull.
95
96
```python { .api }
97
def get_security(self, username=''):
98
"""
99
Get security question for additional verification.
100
101
Parameters:
102
- username (str): Email or phone number used for login
103
104
Returns:
105
dict: Security question details including question_id and question text
106
"""
107
108
def next_security(self, username=''):
109
"""
110
Get next security question if multiple are available.
111
112
Parameters:
113
- username (str): Email or phone number used for login
114
115
Returns:
116
dict: Next security question details
117
"""
118
119
def check_security(self, username='', question_id='', question_answer=''):
120
"""
121
Submit answer to security question.
122
123
Parameters:
124
- username (str): Email or phone number used for login
125
- question_id (str): ID of the security question being answered
126
- question_answer (str): Answer to the security question
127
128
Returns:
129
dict: Verification result
130
"""
131
```
132
133
### Interactive Login
134
135
Convenient interactive login method with prompts for all required information.
136
137
```python { .api }
138
def login_prompt(self):
139
"""
140
Interactive login with prompts for username, password, MFA, and security questions.
141
142
Returns:
143
dict: Login response after successful authentication
144
"""
145
```
146
147
Usage example:
148
149
```python
150
wb = webull()
151
# Prompts user for all required login information
152
wb.login_prompt()
153
```
154
155
### Trading Token
156
157
Obtain trading token required for placing, modifying, or cancelling orders.
158
159
```python { .api }
160
def get_trade_token(self, password=''):
161
"""
162
Get trading token required for order operations.
163
164
Parameters:
165
- password (str): Trading password (may be same as login password)
166
167
Returns:
168
bool: True if trade token obtained successfully, False otherwise
169
"""
170
```
171
172
Usage example:
173
174
```python
175
# Get trade token for order operations
176
success = wb.get_trade_token('trading_password')
177
if success:
178
print("Trade token obtained successfully")
179
else:
180
print("Failed to get trade token")
181
```
182
183
### Token-Based Authentication
184
185
Alternative authentication using existing access tokens.
186
187
```python { .api }
188
def api_login(self, access_token='', refresh_token='', token_expire='', uuid='', mfa=''):
189
"""
190
Authenticate using existing tokens instead of username/password.
191
192
Parameters:
193
- access_token (str): Valid access token
194
- refresh_token (str): Refresh token for token renewal
195
- token_expire (str): Token expiration timestamp
196
- uuid (str): User UUID associated with tokens
197
- mfa (str, optional): MFA code if required
198
199
Returns:
200
dict: Authentication result
201
"""
202
```
203
204
### Session Management
205
206
Manage authentication sessions and token refresh.
207
208
```python { .api }
209
def refresh_login(self, save_token=False, token_path=None):
210
"""
211
Refresh authentication using stored refresh token.
212
213
Parameters:
214
- save_token (bool, optional): Whether to save refreshed tokens
215
- token_path (str, optional): Custom path for token file
216
217
Returns:
218
dict: Refresh result with new tokens
219
"""
220
221
def logout(self):
222
"""
223
Log out from Webull and invalidate session.
224
225
Returns:
226
int: HTTP status code (200 for success)
227
"""
228
229
def is_logged_in(self):
230
"""
231
Check if user is currently logged in with valid session.
232
233
Returns:
234
bool: True if logged in, False otherwise
235
"""
236
```
237
238
Usage example:
239
240
```python
241
# Check login status
242
if wb.is_logged_in():
243
print("User is logged in")
244
else:
245
print("User needs to log in")
246
247
# Refresh tokens
248
wb.refresh_login(save_token=True)
249
250
# Logout
251
wb.logout()
252
```
253
254
### Account Type Detection
255
256
Determine account type and capabilities.
257
258
```python { .api }
259
def get_account_type(self, username=''):
260
"""
261
Get account type information for user.
262
263
Parameters:
264
- username (str, optional): Username to check account type for
265
266
Returns:
267
dict: Account type and capabilities information
268
"""
269
```
270
271
## Authentication Flow Example
272
273
Complete authentication flow handling all possible requirements:
274
275
```python
276
from webull import webull
277
278
wb = webull()
279
280
try:
281
# Initial login attempt
282
response = wb.login('user@example.com', 'password123')
283
284
# Handle MFA if required
285
if 'mfa_required' in response:
286
wb.get_mfa('user@example.com')
287
mfa_code = input("Enter MFA code: ")
288
wb.check_mfa('user@example.com', mfa_code)
289
290
# Handle security question if required
291
if 'security_required' in response:
292
security = wb.get_security('user@example.com')
293
print(f"Security question: {security['question']}")
294
answer = input("Answer: ")
295
wb.check_security('user@example.com', security['question_id'], answer)
296
297
# Get trading token for order operations
298
trade_success = wb.get_trade_token('trading_password')
299
300
if wb.is_logged_in() and trade_success:
301
print("Successfully authenticated and ready for trading")
302
303
except ValueError as e:
304
print(f"Authentication failed: {e}")
305
```