0
# Authentication Methods
1

2
Comprehensive authentication support for various Salesforce deployment scenarios, including traditional password authentication, modern OAuth 2.0 flows, JWT bearer tokens for server-to-server integration, and direct session access for specialized use cases.
3

4
## Authentication Function
5

6
### SalesforceLogin
7

8
Primary authentication function that handles multiple authentication methods and returns session credentials for Salesforce API access.
9

10
```python { .api }
11
def SalesforceLogin(
12
    username=None,
13
    password=None,
14
    security_token=None,
15
    organizationId=None,
16
    sf_version="59.0",
17
    proxies=None,
18
    session=None,
19
    client_id=None,
20
    domain=None,
21
    instance_url=None,
22
    consumer_key=None,
23
    consumer_secret=None,
24
    privatekey_file=None,
25
    privatekey=None,
26
    scratch_url=None
27
):
28
    """
29
    Authenticate with Salesforce using various methods.
30

31
    Parameters:
32
    - username: Salesforce username
33
    - password: Salesforce password  
34
    - security_token: Security token (required for password auth outside trusted IP ranges)
35
    - organizationId: Organization ID for IP filtering authentication
36
    - sf_version: Salesforce API version (default: "59.0")
37
    - proxies: HTTP proxy configuration
38
    - session: Custom requests.Session object
39
    - client_id: Connected App client ID
40
    - domain: Salesforce domain (login.salesforce.com, test.salesforce.com, etc.)
41
    - instance_url: Direct Salesforce instance URL
42
    - consumer_key: OAuth Consumer Key for Connected Apps
43
    - consumer_secret: OAuth Consumer Secret for Connected Apps
44
    - privatekey_file: Path to private key file for JWT authentication
45
    - privatekey: Private key content for JWT authentication
46
    - scratch_url: Scratch org URL for development
47

48
    Returns:
49
    Tuple[str, str]: (session_id, sf_instance) for authenticated session
50
    """
51
```
52

53
## Salesforce Class Authentication
54

55
The Salesforce class constructor supports all authentication methods through its parameters, automatically selecting the appropriate authentication flow based on provided credentials.
56

57
```python { .api }
58
class Salesforce:
59
    def __init__(
60
        self,
61
        username=None,
62
        password=None,
63
        security_token=None,
64
        session_id=None,
65
        instance=None,
66
        instance_url=None,
67
        organizationId=None,
68
        version="59.0",
69
        proxies=None,
70
        session=None,
71
        client_id=None,
72
        domain=None,
73
        consumer_key=None,
74
        consumer_secret=None,
75
        privatekey_file=None,
76
        privatekey=None,
77
        parse_float=None,
78
        object_pairs_hook=dict
79
    ):
80
        """
81
        Initialize Salesforce client with authentication.
82

83
        Parameters:
84
        - username: Salesforce username
85
        - password: Salesforce password
86
        - security_token: Security token for password authentication
87
        - session_id: Existing session ID for direct access
88
        - instance: Salesforce instance domain (e.g., 'na1', 'eu0')
89
        - instance_url: Complete instance URL
90
        - organizationId: Organization ID for IP filtering
91
        - version: API version string (default: "59.0")
92
        - proxies: HTTP proxy configuration dictionary
93
        - session: Custom requests.Session object
94
        - client_id: Connected App client identifier
95
        - domain: Authentication domain (login.salesforce.com, test.salesforce.com)
96
        - consumer_key: OAuth Consumer Key for Connected Apps
97
        - consumer_secret: OAuth Consumer Secret for Connected Apps
98
        - privatekey_file: Path to private key file for JWT flows
99
        - privatekey: Private key content string for JWT flows
100
        - parse_float: Custom JSON float parser
101
        - object_pairs_hook: Custom JSON object hook (default: dict)
102
        """
103
```
104

105
## Authentication Methods
106

107
### 1. Password Authentication
108

109
Traditional username/password authentication with security token, suitable for interactive applications and development environments.
110

111
```python
112
from simple_salesforce import Salesforce
113

114
# Basic password authentication
115
sf = Salesforce(
116
    username='user@example.com',
117
    password='mypassword',
118
    security_token='mytoken'
119
)
120

121
# With custom domain (for sandbox/custom domains)
122
sf = Salesforce(
123
    username='user@example.com',
124
    password='mypassword',
125
    security_token='mytoken',
126
    domain='test.salesforce.com'  # For sandbox
127
)
128

129
# With organization ID (for IP filtering)
130
sf = Salesforce(
131
    username='user@example.com',
132
    password='mypassword',
133
    organizationId='00D000000000000'
134
)
135
```
136

137
### 2. OAuth 2.0 Connected App Authentication
138

139
OAuth authentication using Connected App credentials, supporting both password grant and client credentials flows.
140

141
```python
142
from simple_salesforce import Salesforce
143

144
# OAuth with username/password grant
145
sf = Salesforce(
146
    username='user@example.com',
147
    password='mypassword',
148
    consumer_key='3MVG9PhR6g6B7ps6...',
149
    consumer_secret='1234567890123456789'
150
)
151

152
# Client credentials flow (no user context)
153
sf = Salesforce(
154
    consumer_key='3MVG9PhR6g6B7ps6...',
155
    consumer_secret='1234567890123456789',
156
    domain='login.salesforce.com'
157
)
158
```
159

160
### 3. JWT Bearer Token Authentication
161

162
Server-to-server authentication using JWT tokens, ideal for automated systems and CI/CD pipelines.
163

164
```python
165
from simple_salesforce import Salesforce
166

167
# JWT with private key file
168
sf = Salesforce(
169
    username='user@example.com',
170
    consumer_key='3MVG9PhR6g6B7ps6...',
171
    privatekey_file='/path/to/private.key'
172
)
173

174
# JWT with inline private key
175
private_key_content = '''-----BEGIN RSA PRIVATE KEY-----
176
MIIEpAIBAAKCAQEA...
177
-----END RSA PRIVATE KEY-----'''
178

179
sf = Salesforce(
180
    username='user@example.com',
181
    consumer_key='3MVG9PhR6g6B7ps6...',
182
    privatekey=private_key_content
183
)
184
```
185

186
### 4. Direct Session Access
187

188
Authentication using existing session ID and instance, useful for applications that manage authentication separately.
189

190
```python
191
from simple_salesforce import Salesforce
192

193
# With session ID and instance domain
194
sf = Salesforce(
195
    session_id='00D50000000IehZ!AQcAQH0dMHZfz972dbC_XM5',
196
    instance='na1'
197
)
198

199
# With session ID and full instance URL
200
sf = Salesforce(
201
    session_id='00D50000000IehZ!AQcAQH0dMHZfz972dbC_XM5',
202
    instance_url='https://na1.salesforce.com'
203
)
204
```
205

206
### 5. Programmatic Authentication
207

208
Using the SalesforceLogin function directly for custom authentication workflows.
209

210
```python
211
from simple_salesforce import SalesforceLogin, Salesforce
212

213
# Separate authentication step
214
session_id, instance = SalesforceLogin(
215
    username='user@example.com',
216
    password='mypassword',
217
    security_token='mytoken'
218
)
219

220
# Use credentials to create client
221
sf = Salesforce(
222
    session_id=session_id,
223
    instance=instance
224
)
225
```
226

227
## Advanced Authentication Options
228

229
### Custom Session Management
230

231
```python
232
import requests
233
from simple_salesforce import Salesforce
234

235
# Custom session with specific configuration
236
custom_session = requests.Session()
237
custom_session.headers.update({'User-Agent': 'MyApp/1.0'})
238

239
sf = Salesforce(
240
    username='user@example.com',
241
    password='mypassword',
242
    security_token='mytoken',
243
    session=custom_session
244
)
245
```
246

247
### Proxy Configuration
248

249
```python
250
from simple_salesforce import Salesforce
251

252
# HTTP proxy configuration
253
proxies = {
254
    'http': 'http://proxy.company.com:8080',
255
    'https': 'https://proxy.company.com:8080'
256
}
257

258
sf = Salesforce(
259
    username='user@example.com',
260
    password='mypassword',
261
    security_token='mytoken',
262
    proxies=proxies
263
)
264
```
265

266
### API Version Selection
267

268
```python
269
from simple_salesforce import Salesforce
270

271
# Specify API version
272
sf = Salesforce(
273
    username='user@example.com',
274
    password='mypassword',
275
    security_token='mytoken',
276
    version='58.0'  # Use specific API version
277
)
278
```
279

280
## Session Properties
281

282
After successful authentication, the Salesforce client provides access to session information:
283

284
```python
285
# Session details
286
print(f"Session ID: {sf.session_id}")
287
print(f"Instance: {sf.sf_instance}")
288
print(f"API Version: {sf.sf_version}")
289
print(f"Base URL: {sf.base_url}")
290

291
# API endpoint URLs
292
print(f"Bulk API URL: {sf.bulk_url}")
293
print(f"Bulk 2.0 API URL: {sf.bulk2_url}")
294
print(f"Metadata API URL: {sf.metadata_url}")
295
print(f"Tooling API URL: {sf.tooling_url}")
296

297
# Check if sandbox
298
is_sandbox = sf.is_sandbox()
299
print(f"Is Sandbox: {is_sandbox}")
300
```
301

302
## Error Handling
303

304
Authentication methods raise specific exceptions for different failure scenarios:
305

306
```python
307
from simple_salesforce import (
308
    Salesforce, 
309
    SalesforceAuthenticationFailed,
310
    SalesforceGeneralError
311
)
312

313
try:
314
    sf = Salesforce(
315
        username='invalid@example.com',
316
        password='wrongpassword',
317
        security_token='badtoken'
318
    )
319
except SalesforceAuthenticationFailed as e:
320
    print(f"Authentication failed: {e}")
321
except SalesforceGeneralError as e:
322
    print(f"General error: {e}")
323
```
324

325
## Supporting Functions
326

327
### SOAP Login
328

329
Low-level SOAP-based authentication function used internally by password authentication.
330

331
```python { .api }
332
def soap_login(
333
    soap_url,
334
    request_body, 
335
    headers,
336
    proxies,
337
    session=None
338
):
339
    """
340
    Perform SOAP-based login to Salesforce.
341
    
342
    Parameters:
343
    - soap_url: SOAP API endpoint URL
344
    - request_body: SOAP request body XML
345
    - headers: HTTP headers dictionary
346
    - proxies: Proxy configuration
347
    - session: Optional requests.Session object
348
    
349
    Returns:
350
    Tuple[str, str]: (session_id, server_url)
351
    """
352
```
353

354
### Token Login  
355

356
Low-level OAuth token-based authentication function used internally by OAuth flows.
357

358
```python { .api }
359
def token_login(
360
    token_url,
361
    token_data,
362
    domain,
363
    consumer_key,
364
    headers,
365
    proxies,
366
    session=None
367
):
368
    """
369
    Perform OAuth token-based login to Salesforce.
370
    
371
    Parameters:
372
    - token_url: OAuth token endpoint URL
373
    - token_data: OAuth request parameters
374
    - domain: Salesforce domain
375
    - consumer_key: OAuth consumer key
376
    - headers: HTTP headers dictionary  
377
    - proxies: Proxy configuration
378
    - session: Optional requests.Session object
379
    
380
    Returns:
381
    Tuple[str, str]: (session_id, instance_url)
382
    """
383
```