Charles Schwab Authentication Module

A comprehensive Python module for handling Charles Schwab API authentication with OAuth 2.0 flow, automatic token management, and Google Cloud Storage integration.

Features

• 🔐 OAuth 2.0 Authentication: Complete implementation of Schwab API OAuth flow
• 🔄 Flexible Token Management: Support for fresh authentication and GCS-stored tokens
• 💾 Token Persistence: Saves access and refresh tokens locally and (optionally) to Google Cloud Storage
• ☁️ Cloud Storage Integration: Automatic token backup, retrieval, and validation from GCS
• 🛡️ Robust Error Handling: Comprehensive error handling for all authentication scenarios
• 🎯 Easy Integration: Simple class-based design for seamless integration into larger projects
• ⚡ Dual Mode Operation: Fresh authentication or GCS-based token refresh
• 🔧 Modular Architecture: Separate GCS module for cloud storage operations

Prerequisites

• Python 3.8+
• Charles Schwab Developer Account
• Registered Schwab API Application
• Google Cloud Storage Account (for cloud token storage)

Installation

1. Clone the repository with submodules:

   git clone --recursive <repository-url>
   cd charles-schwab-authentication-module

2. Create and activate a virtual environment:

   # Create virtual environment
   python -m venv venv
   
   # Activate virtual environment
   # On macOS/Linux:
   source venv/bin/activate
   
   # On Windows:
   venv\Scripts\activate

3. Install required dependencies:

   # Ensure pip is up to date
   pip install --upgrade pip
   
   # Install dependencies
   pip install -r requirements.txt

4. Initialize submodules:

   git submodule update --init --recursive

Setup

1. Get Schwab API Credentials

1. Visit the Charles Schwab Developer Portal
2. Create a developer account
3. Register a new application
4. Note your App Key and App Secret
5. Set your redirect URI to https://127.0.0.1

2. Set up Google Cloud Storage

1. Create a Google Cloud Storage bucket for token storage
2. Set up a service account with Storage Object Admin permissions
3. Download the service account key (JSON format)
4. Configure the GOOGLE_APPLICATION_CREDENTIALS environment variable

3. Configure Environment Variables

IMPORTANT: You must create a .env file in the main directory for the application to work properly.

1. Copy the example file:

   cp gcs-python-module/env.example .env

2. Edit the .env file with your actual credentials:

   # Schwab API Configuration
   SCHWAB_APP_KEY=your-actual-schwab-app-key
   SCHWAB_APP_SECRET=your-actual-schwab-app-secret
   
   # Google Cloud Storage Configuration
   GCS_BUCKET_NAME=your-actual-gcs-bucket-name
   GOOGLE_APPLICATION_CREDENTIALS=service-account-credentials.json

3. Replace the placeholder values:

   • your-actual-schwab-app-key: Your Schwab API App Key
   • your-actual-schwab-app-secret: Your Schwab API App Secret
   • your-actual-gcs-bucket-name: Your Google Cloud Storage bucket name
   • service-account-credentials.json: Path to your GCS service account key file (usually just the filename if it's in the same directory)

Note: If you don't have a GCS bucket set up, you can leave GCS_BUCKET_NAME empty, but the cloud storage features won't work.

Usage

Method 1: Fresh Authentication (Interactive)

Run the script to authenticate locally and upload refresh token to GCS:

# Authenticate interactively, cache tokens locally, and push them to GCS
python schwab_authentication_client.py --authenticate
# or simply (default behavior)
python schwab_authentication_client.py

This will:

1. Prompt you to visit the authorization URL
2. Ask you to paste the redirect URL after authorization
3. Generate fresh access and refresh tokens
4. Persist both tokens to local files (schwab_access_token.txt, schwab_refresh_token.txt)
5. Upload both token files to Google Cloud Storage (when configured)

Method 2: GCS-Based Token Refresh (Automated)

Get a new access token using the refresh token stored in Google Cloud Storage:

python schwab_authentication_client.py --get-access-token

This will:

1. Try the cached access token stored locally
2. Fall back to the access token cached in Google Cloud Storage
3. Refresh the access token using a local refresh token
4. Refresh using a GCS refresh token if the local copy is missing or invalid
5. Run the OAuth workflow if no refresh tokens are available
6. Perfect for automated scripts and services that need reliable token rotation

Expected Output

When you run the program, you'll see:

=== GETTING FRESH TOKENS ===
Getting new Schwab tokens...

1. Visit this URL: https://api.schwabapi.com/v1/oauth/authorize?client_id=...
2. Log in and authorize the app
3. You'll be redirected to a URL that looks like:
   https://127.0.0.1/?code=LONG_CODE_HERE&session=...
4. Copy the ENTIRE redirect URL

Paste the full redirect URL here: [YOU PASTE THE URL HERE]
Extracted code: ABC123...
Tokens obtained successfully!
Access Token: eyJ0eXAiOiJKV1QiLCJ...
Refresh Token: eyJ0eXAiOiJKV1QiLCJ...
Refresh token saved to schwab_refresh_token.txt
File schwab_refresh_token.txt uploaded to schwab_refresh_token.txt.
✅ Tokens obtained and uploaded to GCS successfully!

API Reference

SchwabAuthenticationClient Class

__init__()

Initializes the authenticator with credentials from environment variables.

Environment Variables Required:

• SCHWAB_APP_KEY: Your Schwab application key
• SCHWAB_APP_SECRET: Your Schwab application secret
• GCS_BUCKET_NAME: Your Google Cloud Storage bucket name (optional)
• GOOGLE_APPLICATION_CREDENTIALS: Path to your GCS service account key file (optional)

get_valid_access_token(use_gcs_refresh_token=False)

Main method to get a valid access token.

Parameters:

• use_gcs_refresh_token (bool): If True, attempts to use GCS-stored refresh token first

Returns:

• str: Valid access token, or None if authentication fails

Example:

from schwab_authentication_client import SchwabAuthenticationClient

auth = SchwabAuthenticationClient()

# Unified workflow (automatically handles cache → GCS → refresh → OAuth)
access_token = auth.get_valid_access_token()

get_valid_refresh_token(include_oauth=True)

Retrieves a refresh token by checking local storage first, then Google Cloud Storage, and optionally triggering the OAuth workflow.

get_latest_access_token()

Convenience wrapper around get_valid_access_token() for backwards compatibility.

save_access_token(access_token) / load_access_token()

Persists and retrieves the cached access token file.

automated_token_management()

Handles the complete fresh token generation workflow.

Returns:

• str: Refresh token, or None if authentication fails

Example:

auth = SchwabAuth()
refresh_token = auth.automated_token_management()

refresh_access_token(refresh_token, app_key, app_secret)

Refreshes access token using refresh token.

Parameters:

• refresh_token (str): The refresh token to use
• app_key (str): Your Schwab application key
• app_secret (str): Your Schwab application secret

Returns:

• str: New access token, or None if refresh fails

save_refresh_token(refresh_token)

Saves refresh token to local file.

Parameters:

• refresh_token (str): The refresh token to save

load_refresh_token()

Loads refresh token from local file.

Returns:

• str: Refresh token if found, None otherwise

upload_refresh_token_to_gcs()

Uploads the local refresh token file to Google Cloud Storage.

download_refresh_token_from_gcs()

Downloads refresh token from Google Cloud Storage to local file.

Returns:

• str: Refresh token if download successful, None otherwise

Integration Examples

Basic Integration

from schwab_authentication_client import SchwabAuthenticationClient

auth = SchwabAuthenticationClient()

# Unified token retrieval (local cache → GCS cache → refresh → OAuth)
access_token = auth.get_valid_access_token()

# Use the token for API calls
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

# Make API requests
import requests
response = requests.get('https://api.schwabapi.com/v1/accounts', headers=headers)

Integration with Streaming Client

from schwab_authentication_client import SchwabAuthenticationClient

auth = SchwabAuthenticationClient()
access_token = auth.get_valid_access_token()

# Use token for WebSocket authentication
streaming_client.login_with_token(access_token)

Automated Script Integration

from schwab_authentication_client import SchwabAuthenticationClient
import time

def get_schwab_data():
    auth = SchwabAuthenticationClient()
    access_token = auth.get_valid_access_token()

    return access_token

# Use in automated scripts
access_token = get_schwab_data()

File Structure

charles-schwab-authentication-module/
├── schwab_authentication_client.py   # Main authentication client
├── schwab_access_token.txt           # Stored access token (auto-generated)
├── schwab_refresh_token.txt          # Stored refresh token (auto-generated)
├── .env                              # Environment variables (you create this)
├── requirements.txt                  # Python dependencies
├── README.md                         # This file
├── .gitmodules                       # Git submodule configuration
└── google-cloud-storage-client/      # Google Cloud Storage module
    ├── google_cloud_storage_client.py  # GCS client class
    ├── requirements.txt              # GCS module dependencies
    ├── README.md                     # GCS module documentation
    └── tests/                        # GCS module tests
        ├── integration_test.py
        └── README.md

Environment Variables

Variable	Description	Required	Default
SCHWAB_APP_KEY	Your Schwab application key	Yes	-
SCHWAB_APP_SECRET	Your Schwab application secret	Yes	-
GCS_BUCKET_NAME	Your Google Cloud Storage bucket name	No	-
GOOGLE_APPLICATION_CREDENTIALS	Path to your GCS service account key file	No	-

Error Handling

The module includes comprehensive error handling for:

• Missing environment variables
• API request failures
• Invalid authorization codes
• Token refresh failures
• File I/O errors
• Google Cloud Storage operation failures
• Network connectivity issues
• Authentication flow interruptions

Security Notes

• Never commit your .env file to version control
• Keep your App Key and App Secret secure
• The refresh token file contains sensitive data - protect it accordingly
• Use HTTPS in production environments
• Store your Google Cloud service account key securely
• Consider using Google Cloud Secret Manager for production deployments
• Rotate credentials regularly for enhanced security

Troubleshooting

Common Issues

1. "No valid refresh token available"

   • Solution: Run the program again to get fresh tokens
   • Check: Ensure GCS bucket exists and is accessible

2. "Error getting tokens"

   • Check: Your App Key and App Secret are correct
   • Verify: Redirect URI matches your app configuration
   • Ensure: Authorization code is complete and unmodified

3. "Failed to get access token"

   • Try: Running the program again to get fresh tokens
   • Check: Internet connection and API credentials
   • Verify: Refresh token hasn't expired

4. Google Cloud Storage Errors

   • Verify: Service account has correct permissions
   • Check: Bucket name is correct and exists
   • Ensure: Service account key file path is correct
   • Test: GCS connectivity and bucket access

5. Environment Variable Issues

   • Missing .env file: Create .env file by copying gcs-python-module/env.example
   • GCS_BUCKET_NAME is None: Add your bucket name to the .env file
   • GOOGLE_APPLICATION_CREDENTIALS not found: Ensure the path to your service account key is correct
   • SCHWAB credentials not loaded: Verify your App Key and App Secret are correct in .env

6. Virtual Environment Issues

   • Ensure: Virtual environment is activated before installing dependencies
   • Fix: Use venv\Scripts\activate on Windows instead of source venv/bin/activate
   • Reinstall: pip install -r requirements.txt if packages aren't found

7. Git Submodule Issues

   • Initialize: git submodule init && git submodule update
   • Recursive: git submodule update --init --recursive
   • Verify: gcs-python-module/ directory exists and contains gcs_client.py

Debug Mode

For debugging, you can add print statements or modify the error messages in the class methods:

# Enable debug output
import logging
logging.basicConfig(level=logging.DEBUG)

# Or add debug prints
auth = SchwabAuth()
print(f"App Key: {auth.APP_KEY[:10]}...")
print(f"GCS Bucket: {auth.GCS_BUCKET_NAME}")

Google Cloud Storage Module

The project includes a comprehensive Google Cloud Storage module (gcs-python-module/) that provides:

• Service Account Authentication: Secure authentication using service account keys
• Comprehensive Operations: Upload, download, list, delete, and manage files and buckets
• Error Handling: Robust error handling with detailed logging
• Type Hints: Full type annotation support for better development experience
• Testing: Integration tests for all GCS operations

See the gcs-python-module/README.md for detailed documentation on the GCS client functionality.

Testing

Run tests with pytest:

pytest tests/

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This tool is for educational and development purposes. Always follow Charles Schwab's API terms of service and rate limiting guidelines. The tool is not intended for production trading without proper testing and validation.

Support

For issues related to:

• Schwab API: Contact Charles Schwab Developer Support
• Google Cloud Storage: Check the GCS module documentation
• This Tool: Open an issue in this repository
• Integration: Check the parent project documentation

Changelog

v2.1.0

• Enhanced GCS Integration: Improved token management with fallback options
• Better Error Handling: More comprehensive error scenarios and recovery
• Updated Documentation: Comprehensive README with integration examples
• Python 3.8+ Support: Updated minimum Python version requirement

v2.0.0

• Added Google Cloud Storage Integration: Automatic token upload to GCS
• Modular Architecture: Separated GCS functionality into dedicated module
• Enhanced Security: Cloud-based token backup and storage
• Comprehensive GCS Client: Full GCS operations support
• Updated Dependencies: Added Google Cloud Storage requirements

v1.0.0

• Initial Release: Class-based architecture
• Fresh Token Generation: Always gets fresh tokens on every run
• Token Persistence: Saves refresh tokens for reference
• Comprehensive Error Handling: Robust error handling for API calls