Configuration Guide

This guide covers all the ways to configure the Upstox TOTP Python SDK for your environment and use case.

Configuration Methods

The SDK supports multiple configuration methods, listed in order of precedence:

Direct instantiation (highest priority)
Environment variables
`.env` file (lowest priority)

Environment Variables

The SDK automatically loads configuration from environment variables. Here are all the supported variables:

Required Variables

Variable	Description
`UPSTOX_USERNAME`	Your 10-digit mobile number registered with Upstox
`UPSTOX_PASSWORD`	Your Upstox login password
`UPSTOX_PIN_CODE`	Your Upstox PIN code (usually 4-6 digits)
`UPSTOX_TOTP_SECRET`	TOTP secret key from your authenticator app setup
`UPSTOX_CLIENT_ID`	API key from your Upstox Developer App
`UPSTOX_CLIENT_SECRET`	API secret from your Upstox Developer App
`UPSTOX_REDIRECT_URI`	Redirect URI configured in your Upstox Developer App

Optional Variables

Variable	Default	Description
`UPSTOX_DEBUG`	`false`	Enable debug logging (true/false)
`UPSTOX_SLEEP_TIME`	`1000`	Delay between requests in milliseconds

Setting Environment Variables

Linux/macOS:

# Set for current session
export UPSTOX_USERNAME=9876543210
export UPSTOX_PASSWORD=your-password
export UPSTOX_PIN_CODE=1234
# ... other variables

# Add to shell profile for persistence
echo 'export UPSTOX_USERNAME=9876543210' >> ~/.bashrc
echo 'export UPSTOX_PASSWORD=your-password' >> ~/.bashrc

Windows:

# Set for current session
set UPSTOX_USERNAME=9876543210
set UPSTOX_PASSWORD=your-password

# Set permanently
setx UPSTOX_USERNAME "9876543210"
setx UPSTOX_PASSWORD "your-password"

.env File Configuration

Create a .env file in your project root for easy configuration:

Basic .env File

# .env

# Upstox Account Credentials
UPSTOX_USERNAME=9876543210
UPSTOX_PASSWORD=your-secure-password
UPSTOX_PIN_CODE=1234

# TOTP Configuration
UPSTOX_TOTP_SECRET=JBSWY3DPEHPK3PXP

# OAuth App Credentials (from Upstox Developer Console)
UPSTOX_CLIENT_ID=your-client-id-here
UPSTOX_CLIENT_SECRET=your-client-secret-here
UPSTOX_REDIRECT_URI=https://your-app.com/callback

# Optional Settings
UPSTOX_DEBUG=false
UPSTOX_SLEEP_TIME=1000

Environment-specific Configuration

Create separate .env files for different environments:

`.env.development`:

# Development environment
UPSTOX_USERNAME=9876543210
UPSTOX_PASSWORD=dev-password
UPSTOX_PIN_CODE=1234
UPSTOX_TOTP_SECRET=DEV-TOTP-SECRET
UPSTOX_CLIENT_ID=dev-client-id
UPSTOX_CLIENT_SECRET=dev-client-secret
UPSTOX_REDIRECT_URI=http://localhost:8080/callback
UPSTOX_DEBUG=true
UPSTOX_SLEEP_TIME=500

`.env.production`:

# Production environment
UPSTOX_USERNAME=9876543210
UPSTOX_PASSWORD=prod-password
UPSTOX_PIN_CODE=1234
UPSTOX_TOTP_SECRET=PROD-TOTP-SECRET
UPSTOX_CLIENT_ID=prod-client-id
UPSTOX_CLIENT_SECRET=prod-client-secret
UPSTOX_REDIRECT_URI=https://myapp.com/callback
UPSTOX_DEBUG=false
UPSTOX_SLEEP_TIME=1000

`.env.staging`:

# Staging environment
UPSTOX_USERNAME=9876543210
UPSTOX_PASSWORD=staging-password
UPSTOX_PIN_CODE=1234
UPSTOX_TOTP_SECRET=STAGING-TOTP-SECRET
UPSTOX_CLIENT_ID=staging-client-id
UPSTOX_CLIENT_SECRET=staging-client-secret
UPSTOX_REDIRECT_URI=https://staging.myapp.com/callback
UPSTOX_DEBUG=true
UPSTOX_SLEEP_TIME=750

Python Configuration

Auto-loading Configuration

from upstox_totp import UpstoxTOTP

# Auto-loads from environment variables or .env file
upx = UpstoxTOTP()

Loading from Specific .env File

from upstox_totp import UpstoxTOTP

# Load from specific environment file
upx = UpstoxTOTP.from_env_file(".env.production")

# Load from different path
upx = UpstoxTOTP.from_env_file("/path/to/config/.env")

Manual Configuration

from upstox_totp import UpstoxTOTP
from pydantic import SecretStr

# Manual configuration (not recommended for production)
upx = UpstoxTOTP(
    username="9876543210",
    password=SecretStr("your-password"),
    pin_code=SecretStr("1234"),
    totp_secret=SecretStr("JBSWY3DPEHPK3PXP"),
    client_id="your-client-id",
    client_secret=SecretStr("your-client-secret"),
    redirect_uri="https://your-app.com/callback",
    debug=True,
    sleep_time=1000
)

Partial Configuration

from upstox_totp import UpstoxTOTP
from pydantic import SecretStr

# Override specific values while auto-loading others
upx = UpstoxTOTP(
    debug=True,  # Override debug mode
    sleep_time=500  # Override sleep time
    # Other values loaded from environment/env file
)

Configuration Validation

Check Environment Setup

from upstox_totp import UpstoxTOTP, ConfigurationError

try:
    upx = UpstoxTOTP()
    print("✅ Configuration is valid")
except ConfigurationError as e:
    print(f"❌ Configuration error: {e}")

Using the CLI

# Check environment configuration
upstox_cli check-env

Example output:

✅ Environment Check Results:

Required Variables:
✅ UPSTOX_USERNAME: ********3210
✅ UPSTOX_PASSWORD: ********** (length: 12)
✅ UPSTOX_PIN_CODE: ****
✅ UPSTOX_TOTP_SECRET: ********** (length: 16)
✅ UPSTOX_CLIENT_ID: ********-****-****
✅ UPSTOX_CLIENT_SECRET: ********** (length: 32)
✅ UPSTOX_REDIRECT_URI: https://myapp.com/callback

Optional Variables:
✅ UPSTOX_DEBUG: false
✅ UPSTOX_SLEEP_TIME: 1000

🎉 All required environment variables are properly configured!

Advanced Configuration

Custom Configuration Class

from pydantic import BaseModel, SecretStr, Field
from upstox_totp import UpstoxTOTP

class CustomConfig(BaseModel):
    username: str = Field(..., min_length=10, max_length=10)
    password: SecretStr
    pin_code: SecretStr
    totp_secret: SecretStr
    client_id: str
    client_secret: SecretStr
    redirect_uri: str = Field(..., regex=r'^https?://')
    debug: bool = False
    sleep_time: int = Field(default=1000, ge=100, le=5000)

# Load config
config = CustomConfig(
    username="9876543210",
    password=SecretStr("password"),
    # ... other fields
)

# Use with UpstoxTOTP
upx = UpstoxTOTP(**config.dict())

Configuration with Secrets Management

Using Azure Key Vault:

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential
from upstox_totp import UpstoxTOTP
from pydantic import SecretStr

# Initialize Key Vault client
credential = DefaultAzureCredential()
client = SecretClient(vault_url="https://your-vault.vault.azure.net/", credential=credential)

# Retrieve secrets
config = {
    "username": client.get_secret("upstox-username").value,
    "password": SecretStr(client.get_secret("upstox-password").value),
    "pin_code": SecretStr(client.get_secret("upstox-pin").value),
    "totp_secret": SecretStr(client.get_secret("upstox-totp-secret").value),
    "client_id": client.get_secret("upstox-client-id").value,
    "client_secret": SecretStr(client.get_secret("upstox-client-secret").value),
    "redirect_uri": client.get_secret("upstox-redirect-uri").value,
}

upx = UpstoxTOTP(**config)

Using AWS Secrets Manager:

import boto3
import json
from upstox_totp import UpstoxTOTP
from pydantic import SecretStr

# Initialize Secrets Manager client
client = boto3.client('secretsmanager', region_name='us-east-1')

# Retrieve secret
response = client.get_secret_value(SecretId='upstox-credentials')
secrets = json.loads(response['SecretString'])

upx = UpstoxTOTP(
    username=secrets['username'],
    password=SecretStr(secrets['password']),
    pin_code=SecretStr(secrets['pin_code']),
    totp_secret=SecretStr(secrets['totp_secret']),
    client_id=secrets['client_id'],
    client_secret=SecretStr(secrets['client_secret']),
    redirect_uri=secrets['redirect_uri']
)

Docker Configuration

Using Environment Variables

FROM python:3.12-slim

# Install package
RUN pip install upstox-totp

# Set environment variables
ENV UPSTOX_USERNAME=9876543210
ENV UPSTOX_PASSWORD=your-password
ENV UPSTOX_PIN_CODE=1234
ENV UPSTOX_TOTP_SECRET=your-totp-secret
ENV UPSTOX_CLIENT_ID=your-client-id
ENV UPSTOX_CLIENT_SECRET=your-client-secret
ENV UPSTOX_REDIRECT_URI=https://your-app.com/callback

# Copy and run your app
COPY . /app
WORKDIR /app
CMD ["python", "main.py"]

Using .env File

FROM python:3.12-slim

RUN pip install upstox-totp

COPY .env /app/.env
COPY . /app
WORKDIR /app

CMD ["python", "main.py"]

Docker Compose

# docker-compose.yml
version: '3.8'

services:
  upstox-app:
    build: .
    environment:
      - UPSTOX_USERNAME=${UPSTOX_USERNAME}
      - UPSTOX_PASSWORD=${UPSTOX_PASSWORD}
      - UPSTOX_PIN_CODE=${UPSTOX_PIN_CODE}
      - UPSTOX_TOTP_SECRET=${UPSTOX_TOTP_SECRET}
      - UPSTOX_CLIENT_ID=${UPSTOX_CLIENT_ID}
      - UPSTOX_CLIENT_SECRET=${UPSTOX_CLIENT_SECRET}
      - UPSTOX_REDIRECT_URI=${UPSTOX_REDIRECT_URI}
    env_file:
      - .env

Configuration Security

Best Practices

Never commit secrets to version control
Use environment variables in production
Rotate credentials regularly
Use secrets management services
Limit access to configuration files

.gitignore Configuration

# .gitignore

# Environment files
.env
.env.local
.env.development
.env.staging
.env.production
.env.*.local

# Configuration files with secrets
config.json
secrets.yaml
credentials.ini

File Permissions

# Secure .env file permissions
chmod 600 .env

# Secure config directory
chmod 700 config/
chmod 600 config/*.env

Configuration Templates

Example .env Template

# .env.example - Template file (safe to commit)

# Upstox Account Credentials
UPSTOX_USERNAME=your-mobile-number-here
UPSTOX_PASSWORD=your-password-here
UPSTOX_PIN_CODE=your-pin-here

# TOTP Configuration
UPSTOX_TOTP_SECRET=your-totp-secret-here

# OAuth App Credentials (from Upstox Developer Console)
UPSTOX_CLIENT_ID=your-client-id-here
UPSTOX_CLIENT_SECRET=your-client-secret-here
UPSTOX_REDIRECT_URI=your-redirect-uri-here

# Optional Settings
UPSTOX_DEBUG=false
UPSTOX_SLEEP_TIME=1000

Setup Script

#!/bin/bash
# setup-env.sh - Environment setup script

if [ ! -f .env ]; then
    echo "Creating .env file from template..."
    cp .env.example .env
    echo "Please edit .env file with your actual credentials"
    echo "Then run: chmod 600 .env"
else
    echo ".env file already exists"
fi

Configuration Validation Script

# validate_config.py

import os
from upstox_totp import UpstoxTOTP, ConfigurationError

def validate_environment():
    """Validate environment configuration."""
    required_vars = [
        'UPSTOX_USERNAME',
        'UPSTOX_PASSWORD',
        'UPSTOX_PIN_CODE',
        'UPSTOX_TOTP_SECRET',
        'UPSTOX_CLIENT_ID',
        'UPSTOX_CLIENT_SECRET',
        'UPSTOX_REDIRECT_URI'
    ]

    missing_vars = []
    for var in required_vars:
        if not os.getenv(var):
            missing_vars.append(var)

    if missing_vars:
        print(f"❌ Missing environment variables: {', '.join(missing_vars)}")
        return False

    try:
        upx = UpstoxTOTP()
        print("✅ Configuration is valid")
        return True
    except ConfigurationError as e:
        print(f"❌ Configuration error: {e}")
        return False

if __name__ == "__main__":
    validate_environment()

Troubleshooting Configuration

Common Issues

“Configuration Error: Missing environment variables”

# Check which variables are set
env | grep UPSTOX

# Use the CLI to check configuration
upstox_cli check-env

“Invalid TOTP secret format”

Ensure TOTP secret is base32 encoded
Remove any spaces or special characters
Check that it’s the correct secret from your authenticator app

“Client ID / Redirect URI mismatch”

Verify credentials in Upstox Developer Console
Ensure redirect_uri exactly matches (including protocol, domain, path)
Check that your app is approved and active

Permission denied errors

# Check file permissions
ls -la .env

# Fix permissions
chmod 600 .env

Testing Configuration

Unit Tests

# test_config.py

import pytest
from upstox_totp import UpstoxTOTP, ConfigurationError
from pydantic import SecretStr

def test_valid_configuration():
    """Test valid configuration."""
    upx = UpstoxTOTP(
        username="9876543210",
        password=SecretStr("password"),
        pin_code=SecretStr("1234"),
        totp_secret=SecretStr("JBSWY3DPEHPK3PXP"),
        client_id="client-id",
        client_secret=SecretStr("client-secret"),
        redirect_uri="https://example.com/callback"
    )
    assert upx.username == "9876543210"

def test_invalid_username():
    """Test invalid username format."""
    with pytest.raises(ConfigurationError):
        UpstoxTOTP(
            username="invalid",  # Should be 10 digits
            password=SecretStr("password"),
            # ... other fields
        )

Configuration Migration

From v1.0 to v1.1

# Old configuration (v1.0)
upx = UpstoxTOTP(
    mobile="9876543210",  # Changed to 'username'
    password="password",
    pin="1234",           # Changed to 'pin_code'
    totp_key="secret"     # Changed to 'totp_secret'
)

# New configuration (v1.1+)
upx = UpstoxTOTP(
    username="9876543210",
    password=SecretStr("password"),
    pin_code=SecretStr("1234"),
    totp_secret=SecretStr("secret")
)

Need Help?

If you’re having configuration issues:

Check the Troubleshooting Guide guide
Review the Quick Start Guide for step-by-step setup
Use upstox_cli check-env to diagnose issues
Create an issue on GitHub