Automatic Token Refresh

This document describes the automatic token refresh and secure storage features in the AxiomTradeAPI-py library.

Overview

The library includes:

Automatic token refresh using the correct API endpoint
Secure token storage with encryption
Automatic token management with configurable options
Backward compatibility with existing code

Key Features

1. Automatic Token Refresh

The library automatically refreshes your access tokens when they expire, using the correct API endpoint:

Endpoint: https://api.axiom.trade/refresh-access-token
Uses proper headers and cookies as required by the API
Handles both cookie-based and JSON-based responses
Automatically saves refreshed tokens (when enabled)

2. Secure Token Storage

Tokens are stored securely on your local machine:

Location: ~/.axiomtradeapi/ directory (Windows: C:\Users\{username}\.axiomtradeapi\)
Encryption: Uses Fernet symmetric encryption from the cryptography library
Permissions: Files are readable only by your user account
Format: Encrypted JSON files

3. Configurable Options

You can control how tokens are managed:

use_saved_tokens=True: Enable automatic token loading/saving (default)
use_saved_tokens=False: Disable automatic token storage
storage_dir: Custom directory for token storage

Usage Examples

Basic Usage with Automatic Token Management

from axiomtradeapi.client import AxiomTradeClient

# Create client with automatic token management (default behavior)
client = AxiomTradeClient(
    username="your_email@example.com",
    password="your_password",
    use_saved_tokens=True  # Default: automatically load/save tokens
)

# The client will:
# 1. Try to load saved tokens
# 2. Refresh them if expired
# 3. Login if no valid tokens exist
# 4. Save new tokens automatically

# Make API calls - authentication is handled automatically
trending = client.get_trending_tokens()

Manual Token Management

from axiomtradeapi.client import AxiomTradeClient

# Disable automatic token storage
client = AxiomTradeClient(use_saved_tokens=False)

# Set tokens manually
client.set_tokens(
    access_token="your_access_token",
    refresh_token="your_refresh_token"
)

# Manually refresh when needed
if not client.is_authenticated():
    client.refresh_access_token()

Using Environment Variables

import os
from axiomtradeapi.client import AxiomTradeClient

# Load tokens from environment
client = AxiomTradeClient(
    auth_token=os.getenv('ACCESS_TOKEN'),
    refresh_token=os.getenv('REFRESH_TOKEN'),
    use_saved_tokens=False  # Don't save env tokens
)

Advanced Authentication Management

from axiomtradeapi.auth.auth_manager import AuthManager

# Create auth manager with custom settings
auth_manager = AuthManager(
    username="your_email@example.com",
    password="your_password",
    storage_dir="/custom/path",  # Custom storage location
    use_saved_tokens=True
)

# Check token status
token_info = auth_manager.get_token_info()
print(f"Authenticated: {token_info['authenticated']}")
print(f"Expires in: {token_info['time_until_expiry']} seconds")

# Force token refresh
if auth_manager.refresh_tokens():
    print("Tokens refreshed successfully!")

# Ensure valid authentication (auto-refresh/login as needed)
if auth_manager.ensure_valid_authentication():
    print("Ready to make API calls!")

API Reference

AxiomTradeClient

Constructor Parameters

username (str, optional): Email for automatic login
password (str, optional): Password for automatic login
auth_token (str, optional): Existing access token
refresh_token (str, optional): Existing refresh token
storage_dir (str, optional): Custom directory for token storage
use_saved_tokens (bool, default=True): Enable automatic token loading/saving

Methods

Authentication Methods

login(email, password): Login with credentials
set_tokens(access_token, refresh_token): Set tokens manually
is_authenticated(): Check if client has valid tokens
refresh_access_token(): Manually refresh access token
ensure_authenticated(): Ensure valid authentication (auto-refresh/login)
logout(): Clear all authentication data

Token Management Methods

get_tokens(): Get current token information
get_token_info_detailed(): Get detailed token status
clear_saved_tokens(): Clear saved tokens from storage
has_saved_tokens(): Check if saved tokens exist

AuthManager

Constructor Parameters

username (str, optional): Email for automatic login
password (str, optional): Password for automatic login
auth_token (str, optional): Existing access token
refresh_token (str, optional): Existing refresh token
storage_dir (str, optional): Custom directory for token storage
use_saved_tokens (bool, default=True): Enable automatic token loading/saving

Methods

authenticate(): Perform full login flow
refresh_tokens(): Refresh access token
ensure_valid_authentication(): Ensure valid tokens (auto-refresh/login)
get_token_info(): Get detailed token information
logout(): Clear all authentication data
clear_saved_tokens(): Clear saved tokens
has_saved_tokens(): Check if saved tokens exist

Security Considerations

Token Storage Security

Tokens are encrypted using Fernet symmetric encryption
Encryption key is stored separately and is user-specific
File permissions are set to be readable only by the user
Storage directory is created with restricted permissions

Best Practices

Use automatic token management for most applications
Disable token storage (use_saved_tokens=False) for:
- Shared environments
- CI/CD pipelines
- When using external token management
Set custom storage directory for applications with specific security requirements
Clear tokens on logout to prevent unauthorized access

Error Handling

The library provides comprehensive error handling:

from axiomtradeapi.client import AxiomTradeClient

client = AxiomTradeClient()

try:
    # This will automatically handle token refresh
    if client.ensure_authenticated():
        trending = client.get_trending_tokens()
    else:
        print("Authentication failed")
except Exception as e:
    print(f"Error: {e}")

Migration from Previous Versions

The new version is backward compatible:

# Old way (still works)
from axiomtradeapi.client import AxiomTradeClient
client = AxiomTradeClient()
client.set_tokens("access_token", "refresh_token")

# New way (recommended)
from axiomtradeapi.client import AxiomTradeClient
client = AxiomTradeClient(
    auth_token="access_token",
    refresh_token="refresh_token"
)
# Tokens are now automatically managed

Environment Variables

You can use environment variables for configuration:

# Windows PowerShell
$env:ACCESS_TOKEN="your_access_token"
$env:REFRESH_TOKEN="your_refresh_token"

# Windows Command Prompt
set ACCESS_TOKEN=your_access_token
set REFRESH_TOKEN=your_refresh_token

# Linux/macOS
export ACCESS_TOKEN="your_access_token"
export REFRESH_TOKEN="your_refresh_token"

import os
from axiomtradeapi.client import AxiomTradeClient

client = AxiomTradeClient(
    auth_token=os.getenv('ACCESS_TOKEN'),
    refresh_token=os.getenv('REFRESH_TOKEN')
)

Troubleshooting

Common Issues

Tokens not being saved
- Check if use_saved_tokens=True (default)
- Verify directory permissions
- Check available disk space
Token refresh fails
- Verify refresh token is valid
- Check network connectivity
- Review error logs for specific issues
Permission errors
- Ensure user has write access to storage directory
- Check if storage directory exists and is accessible

Debug Logging

Enable debug logging to see what’s happening:

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

from axiomtradeapi.client import AxiomTradeClient
client = AxiomTradeClient()

This will show detailed information about:

Token loading/saving operations
Refresh attempts
Authentication status
API requests

Dependencies

The new features require the cryptography library:

pip install cryptography>=3.4.8

This is automatically included when you install the updated package.