Upstox Auth Pro 🚀

Upstox Auth Pro is a high-performance, production-grade Python SDK designed to automate the Upstox OAuth2 login flow. It leverages Playwright for robust browser automation, pyotp for seamless 2FA, and a pluggable storage system for secure token management.

---

📚 Documentation

For full documentation, API reference, and advanced usage, visit: https://growthquantix.github.io/upstox-auth-pro/

---

📋 Table of Contents

• ✨ Key Features
• 🛠️ Requirements
• 🚀 Installation
• 📖 Quick Start
• 💻 CLI Usage
• ⚙️ Configuration (.env)
• 📑 API Reference
• 🔍 Troubleshooting
• 🤝 Contributing
• 👨‍💻 Maintainer

---

✨ Key Features

• Maximum Automation: Fully automated versioning and publishing using Semantic Release.
• Robust Browser Engine: Uses Playwright with advanced stealth configurations to bypass bot detection.
• Intelligent PIN Entry: Dynamically handles both single-field and multi-field PIN input interfaces.
• Auto-Retry Mechanism: Built-in retry logic with exponential backoff for transient network failures.
• Smart Token Management: IST-aware token expiry validation (Upstox tokens expire daily at 3:30 AM IST).
• Diagnostic Mode: Automatic screenshots on failure and comprehensive logging for easy debugging.
• Production Ready: Clean, type-hinted API and a powerful CLI tool for rapid development.

---

🛠️ Requirements

• Python: 3.8, 3.9, 3.10, 3.11, or 3.12.
• Browser: Chromium (managed automatically via Playwright).
• Upstox API: Active App Credentials (API Key, Secret, Redirect URI).

---

🚀 Installation

1. Install the SDK

pip install upstox-auth-pro

2. Install Browser Dependencies

playwright install chromium

---

📖 Quick Start

import asyncio
from upstox_auth import FileStorage, UpstoxAuthenticator

async def main():
    # 1. Initialize the authenticator
    auth = UpstoxAuthenticator(
        api_key="YOUR_API_KEY",
        api_secret="YOUR_API_SECRET",
        redirect_uri="https://localhost:8000/callback",
        mobile_no="9876543210",
        pin="123456",
        totp_key="YOUR_TOTP_SECRET",
        storage=FileStorage("tokens/upstox_token.json"), # Auto-creates directories
        headless=True,
        retries=2 # Number of retries on transient failures
    )

    # 2. Get your access token (automatically handles login/expiry/storage)
    try:
        token = await auth.get_access_token()
        print(f"Authenticated! Token: {token[:10]}...")
    except Exception as e:
        print(f"Authentication failed: {e}")

if __name__ == "__main__":
    asyncio.run(main())

---

💻 CLI Usage

You can also use the SDK directly from your terminal. It automatically loads credentials from a .env file.

# Basic usage (returns token to stdout)
upstox-auth

# Run using python module syntax
python -m upstox_auth

# Debug mode: see the browser while it logs in
upstox-auth --visible

# Force a fresh login (bypass stored token)
upstox-auth --force --storage production_token.json

---

⚙️ Configuration (.env)

We recommend using a .env file for secure credential management:

UPSTOX_API_KEY=your_api_key_here
UPSTOX_API_SECRET=your_api_secret_here
UPSTOX_REDIRECT_URI=https://localhost:8000/callback
UPSTOX_MOBILE=9876543210
UPSTOX_PIN=123456
UPSTOX_TOTP_KEY=JBSWY3DPEHPK3PXP

---

📑 API Reference

UpstoxAuthenticator

Parameter	Type	Default	Description
api_key	str	Required	Upstox API Key.
api_secret	str	Required	Upstox API Secret.
redirect_uri	str	Required	Must match Upstox portal config.
mobile_no	str	Required	Registered mobile number.
pin	str	Required	6-digit login PIN.
totp_key	str	Required	2FA Secret Key (not the 6-digit code).
storage	BaseStorage	MemoryStorage	Token storage provider.
headless	bool	True	Run browser without UI.
retries	int	2	Automation retry attempts.

---

🔍 Troubleshooting & Logging

Verbose Logs

If you encounter issues, enable logging to see the step-by-step automation:

import logging
logging.basicConfig(level=logging.INFO)

Common Failures

• Zscaler/Firewall: If you see "Access blocked by network filter", ensure api.upstox.com is whitelisted.
• Selector Timeouts: On failure, a diagnostic screenshot is saved to .tmp/error_mobile_selector.png.
• Redirect URI Mismatch: The redirect_uri must be identical to the one set in your Upstox Developer Portal (including trailing slashes).

---

👨‍💻 Maintainer

Developed and maintained by Brijesh Yadav.

For any queries, feel free to reach out via:

• Email: brijeshyadav30599@gmail.com
• GitHub: brijeshyadav30599
• Organization: GrowthQuantix

⭐ Show Your Support

If this project helped you automate your trading flow, please give it a Star on GitHub! It helps more developers find this tool.

---

Disclaimer: This is an unofficial library and is not affiliated with Upstox. Use at your own risk.