Authentication

Salesforce Toolkit supports multiple authentication methods to connect to Salesforce. This guide will help you choose the right authentication method for your use case.

Quick Reference

Here’s a quick reference table of available authentication methods:

Method	Use Case	Security Level
CLI Authentication	Local development with Salesforce CLI installed	High
OAuth Username-Password	Simple scripting with username/password	Medium
OAuth JWT Bearer	Server-to-server integration	High
OAuth Client Credentials	Service integration with client credentials	High
SOAP Security Token	Legacy applications needing security token auth	Medium
SOAP IP Filtering	Orgs with IP restrictions enabled	Medium

Lazy Authentication (Auto-selection)

For most use cases, you can use the lazy_login function which automatically selects the appropriate authentication method based on the provided parameters:

from sf_toolkit import SalesforceClient, lazy_login

# CLI Authentication
client = SalesforceClient(login=lazy_login(sf_cli_alias="my-org"))

# OAuth JWT Bearer Flow
with open("private_key.pem", "rb") as f:
    private_key_data = f.read()
client = SalesforceClient(
    login=lazy_login(
        username="user@example.com",
        consumer_key="your_consumer_key",
        private_key=private_key_data
    )
)

# Username-Password Flow
client = SalesforceClient(
    login=lazy_login(
        username="user@example.com",
        password="password",
        consumer_key="your_consumer_key",
        consumer_secret="your_consumer_secret"
    )
)

CLI-based Authentication

If you’re using the Salesforce CLI (sf or sfdx), this is the simplest method for local development:

from sf_toolkit import SalesforceClient, cli_login

# Use default org from CLI
client = SalesforceClient(login=cli_login())

# Use a specific org by alias or username
client = SalesforceClient(login=cli_login(alias_or_username="my-dev-org"))

# Specify the path to the CLI executable
client = SalesforceClient(login=cli_login(sf_exec_path="/custom/path/to/sf"))

This method:

Uses the existing authentication from your Salesforce CLI
Doesn’t require storing credentials in your code
Works with any authentication method supported by the CLI
Automatically handles token refresh

OAuth 2.0 Authentication

Salesforce Toolkit supports several OAuth 2.0 flows for different use cases:

Username-Password Flow

For simple scripting and personal applications:

from sf_toolkit import SalesforceClient, password_login

client = SalesforceClient(
    login=password_login(
        username="user@example.com",
        password="password",
        consumer_key="your_consumer_key",
        consumer_secret="your_consumer_secret",
        domain="login"  # or your custom domain
    )
)

Warning

This method requires storing your password in your code or configuration. Consider using other methods for production applications.

JWT Bearer Flow

For secure server-to-server integration:

import pathlib
from sf_toolkit import SalesforceClient, public_key_auth_login

# Load private key
private_key_path = pathlib.Path("path/to/private_key.key")
private_key = private_key_path.read_bytes()

client = SalesforceClient(
    login=public_key_auth_login(
        username="user@example.com",
        consumer_key="your_connected_app_consumer_key",
        private_key=private_key,
        domain="login"  # or your custom domain
    )
)

This method:

Does not require storing user passwords
Uses digital signatures to securely authenticate
Is ideal for automated applications and server-to-server integrations
Requires a connected app with a digital certificate

Client Credentials Flow

For service-to-service integration without a specific user context:

from sf_toolkit import SalesforceClient, client_credentials_flow_login

client = SalesforceClient(
    login=client_credentials_flow_login(
        consumer_key="your_consumer_key",
        consumer_secret="your_consumer_secret",
        domain="login"  # or your custom domain
    )
)

This method:

Uses client credentials for authentication without a user context
Requires a connected app configured for the client credentials flow
Is useful for background service integrations

SOAP Authentication

Salesforce Toolkit supports various SOAP-based authentication methods for compatibility with different security configurations:

Security Token Authentication

For orgs that require a security token with the password:

from sf_toolkit import SalesforceClient, security_token_login

client = SalesforceClient(
    login=security_token_login(
        username="user@example.com",
        password="password",
        security_token="your_security_token",
        client_id="YourAppName",  # Optional identifier for your app
        domain="login",  # Or your custom domain
        api_version=63.0  # Salesforce API version
    )
)

IP Filtering Authentication

For orgs with IP filtering enabled that allow specific IPs to skip the security token:

from sf_toolkit import SalesforceClient, ip_filtering_non_service_login

client = SalesforceClient(
    login=ip_filtering_non_service_login(
        username="user@example.com",
        password="password",
        client_id="YourAppName",  # Optional
        domain="login",  # Or your custom domain
        api_version=63.0  # Salesforce API version
    )
)

Organization-Scoped Login

For logging in to a specific organization within a multi-org setup:

from sf_toolkit import SalesforceClient, ip_filtering_org_login

client = SalesforceClient(
    login=ip_filtering_org_login(
        username="user@example.com",
        password="password",
        organizationId="00Dxxxxxxxxxx",  # Your org ID
        client_id="YourAppName",  # Optional
        domain="login",  # Or your custom domain
        api_version=63.0  # Salesforce API version
    )
)

Using Tokens Directly

If you already have a Salesforce access token and instance URL:

from sf_toolkit import SalesforceClient, SalesforceToken
from httpx import URL

# Create a token directly
token = SalesforceToken(
    instance=URL("https://myinstance.my.salesforce.com"),
    token="00D..."  # Your access token
)

# Use the token
client = SalesforceClient(token=token)

Token Refresh and Callbacks

You can register a callback function to be executed when a token is refreshed:

def token_updated(token):
    # Save token to database or file
    print(f"Token updated for {token.instance}")
    with open("token.txt", "w") as f:
        f.write(f"{token.instance}|{token.token}")

client = SalesforceClient(
    login=cli_login(),
    token_refresh_callback=token_updated
)

Best Practices

Don’t hardcode credentials: Store secrets in environment variables or a secure credential store.

import os

client = SalesforceClient(
    login=password_login(
        username=os.environ["SF_USERNAME"],
        password=os.environ["SF_PASSWORD"],
        consumer_key=os.environ["SF_CONSUMER_KEY"],
        consumer_secret=os.environ["SF_CONSUMER_SECRET"]
    )
)

Use the strongest authentication method available: - JWT Bearer for server applications - CLI login for development - Avoid storing passwords in code

Implement token persistence to avoid unnecessary authentications:

import os
import json
from httpx import URL
from sf_toolkit import SalesforceClient, SalesforceToken, cli_login

# Try to load saved token
token = None
token_file = "saved_token.json"

if os.path.exists(token_file):
    try:
        with open(token_file, "r") as f:
            data = json.load(f)
            token = SalesforceToken(
                instance=URL(data["instance"]),
                token=data["token"]
            )
    except Exception as e:
        print(f"Error loading token: {e}")

# Save token on refresh
def save_token(token):
    with open(token_file, "w") as f:
        json.dump({
            "instance": str(token.instance),
            "token": token.token
        }, f)

# Create client with token or login method
client = SalesforceClient(
    login=None if token else cli_login(),
    token=token,
    token_refresh_callback=save_token
)

Handle token expiration gracefully: Salesforce Toolkit automatically attempts to refresh tokens when they expire during a request.

Authentication Classes

Under the hood, these authentication methods use these core classes:

SalesforceAuth - HTTPX authentication class that handles token management and refresh
SalesforceToken - Named tuple that represents a Salesforce access token with instance URL
SalesforceLogin - A callable that performs the authentication flow and returns a token
TokenRefreshCallback - A callable type for token refresh callbacks