🔐 Secure Token¶

A simple and secure token management library for Python applications. Generate, validate, and manage encrypted tokens with ease.

Perfect for authentication, API security, session management, and microservices.

✨ Features¶

🛡️ Secure: Fernet encryption with PBKDF2 key derivation
⚡ Fast: Stateless design, no database required
🎯 Simple: Easy-to-use API with clear examples
🔧 Flexible: Custom permissions and expiration times
📦 Lightweight: Minimal dependencies

🚀 Installation¶

pip install secure-token

💡 Quick Start¶

A simple example to get you started:

from secure_token import SecureTokenManager

# 1. Create token manager
manager = SecureTokenManager()

# 2. Generate a token (simplest way)
token = manager.generate_token(user_id="user_123")

# 3. Validate the token
result = manager.validate_token(token)
print(f"User: {result['user_id']}")  # User: user_123

Example with Permissions¶

# Token with different permissions
token = manager.generate_token(
    user_id="john_doe",
    permissions=["read", "write"],
    expires_in_hours=24
)

# Check specific permission
try:
    manager.check_permission(token, "write")
    print("Access granted!")
except PermissionDeniedError:
    print("Access denied!")

📚 Methods Guide¶

1️⃣ generate_token - Create Token¶

Generates a secure encrypted token.

Parameters: - user_id (required): User identifier - permissions (optional): List of permissions - expires_in_hours (optional): Expiration time in hours - additional_data (optional): Additional data to store

Simple Examples:

from secure_token import SecureTokenManager

manager = SecureTokenManager()

# Example 1: Simplest form
token = manager.generate_token(user_id="user_123")

# Example 2: With permissions
token = manager.generate_token(
    user_id="admin_456",
    permissions=["read", "write", "delete"]
)

# Example 3: Complete with all options
token = manager.generate_token(
    user_id="user_789",
    permissions=["admin"],
    expires_in_hours=48,  # 2 days
    additional_data={
        "role": "administrator",
        "department": "IT"
    }
)

2️⃣ validate_token - Validate Token¶

Validates a token and returns its information.

Returns: - valid: Token validity status - user_id: User identifier - permissions: List of permissions - expires_at: Expiration datetime - time_remaining: Time remaining until expiration

Simple Examples:

# Example 1: Simple validation
result = manager.validate_token(token)
if result['valid']:
    print(f"User: {result['user_id']}")

# Example 2: Get complete information
result = manager.validate_token(token)
user_id = result['user_id']
permissions = result['permissions']
time_left = result['time_remaining']
print(f"User {user_id} - Time left: {time_left}")

# Example 3: Error handling
from secure_token import TokenExpiredError, InvalidTokenError

try:
    result = manager.validate_token(token)
    print("Token is valid!")
except TokenExpiredError:
    print("Token has expired!")
except InvalidTokenError:
    print("Token is invalid!")

3️⃣ check_permission - Check Permission¶

Checks if a user has a specific permission.

Parameters: - token: User's token - required_permission: Required permission to check

Simple Examples:

from secure_token import PermissionDeniedError

# Example 1: Simple check
try:
    manager.check_permission(token, "admin")
    print("User is admin!")
except PermissionDeniedError:
    print("User is not admin!")

# Example 2: Check multiple permissions
permissions_to_check = ["read", "write", "delete"]

for perm in permissions_to_check:
    try:
        manager.check_permission(token, perm)
        print(f"✓ Has {perm} access")
    except PermissionDeniedError:
        print(f"✗ No {perm} access")

# Example 3: Use in a function
def has_admin_access(token):
    try:
        return manager.check_permission(token, "admin")
    except:
        return False

if has_admin_access(token):
    print("Welcome to admin panel!")

4️⃣ refresh_token - Refresh Token¶

Creates a new token with the same information.

Parameters: - token: Current token - new_expires_in_hours (optional): New expiration time

Simple Examples:

# Example 1: Simple refresh (24 hours default)
new_token = manager.refresh_token(old_token)

# Example 2: Refresh with custom time
new_token = manager.refresh_token(old_token, new_expires_in_hours=72)

# Example 3: Auto-refresh
def auto_refresh_if_needed(token):
    """Refresh if less than 2 hours remaining"""
    try:
        info = manager.get_token_info(token)
        remaining = info['time_remaining']

        # If less than 2 hours remaining
        if "1:" in remaining or "0:" in remaining:
            return manager.refresh_token(token)
        return token
    except:
        return None

refreshed = auto_refresh_if_needed(my_token)

5️⃣ get_token_info - Get Token Information¶

Returns complete token information.

Returns: - token_id: Unique identifier - user_id: User identifier - permissions: List of permissions - time_remaining: Time remaining until expiration - And more...

Simple Examples:

# Example 1: Get simple information
info = manager.get_token_info(token)
print(f"User: {info['user_id']}")
print(f"Time left: {info['time_remaining']}")

# Example 2: Display complete information
info = manager.get_token_info(token)
print(f"""
📋 Token Information:
- User: {info['user_id']}
- Permissions: {info['permissions']}
- Issued at: {info['issued_at']}
- Expires at: {info['expires_at']}
- Time remaining: {info['time_remaining']}
""")

# Example 3: Check token status
info = manager.get_token_info(token)
if info['valid']:
    print("✓ Token is active")
    print(f"⏱ {info['time_remaining']} remaining")
else:
    print("✗ Token is inactive")

6️⃣ export_config - Export Configuration¶

Returns encryption configuration (for backup purposes).

Simple Examples:

# Get configuration
config = manager.export_config()
print(f"Algorithm: {config['algorithm']}")
print(f"Version: {config['version']}")

# Save for backup
import json

config = manager.export_config()
with open('backup_config.json', 'w') as f:
    json.dump(config, f)

🔧 Configuration¶

Configuration Methods¶

1️⃣ Simple Method (Default):

from secure_token import SecureTokenManager

# Automatic settings
manager = SecureTokenManager()

2️⃣ With Environment Variables:

import os
from secure_token import SecureTokenManager

# Set variables
os.environ['SECRET_KEY'] = 'MySecretKey@123'
os.environ['DEFAULT_EXPIRATION_HOURS'] = '12'

manager = SecureTokenManager()

3️⃣ With .env File:

# Create .env file:
SECRET_KEY=MySecretKey@123
DEFAULT_EXPIRATION_HOURS=12

from dotenv import load_dotenv
from secure_token import SecureTokenManager

load_dotenv()
manager = SecureTokenManager()

4️⃣ With Custom Settings:

from secure_token import SecureTokenManager, Settings

settings = Settings(
    SECRET_KEY="MyCustomKey@456!",
    DEFAULT_EXPIRATION_HOURS=48
)

manager = SecureTokenManager(settings_instance=settings)

🔒 Security Note: Settings automatically validates all parameters during initialization. If you provide invalid SECRET_KEY, SALT, or expiration time, it will raise an error immediately.

Settings Validation Requirements¶

SECRET_KEY Requirements: - Minimum 16 characters - Contains uppercase and lowercase letters - At least one number - At least one special character (@$!%*?&#)

Valid SECRET_KEY Examples:

# ✓ Valid
"MyPassword@123"
"SecureApp#2025"
"StrongKey!Abc123"

# ✗ Invalid - Will raise TokenError
"weak"           # Too short
"nocapitals123"  # No uppercase letters
"NoNumbers!"     # No numbers
"NoSpecial123"   # No special characters

Example with Error Handling:

from secure_token import Settings, SecureTokenManager, TokenError

try:
    settings = Settings(
        SECRET_KEY="weak",  # Too weak!
        DEFAULT_EXPIRATION_HOURS=24
    )
except TokenError as e:
    print(f"Settings validation error: {e}")

# Valid settings
settings = Settings(
    SECRET_KEY="MyStrongPassword@123",
    DEFAULT_EXPIRATION_HOURS=24
)
manager = SecureTokenManager(settings_instance=settings)

⚠️ Error Handling¶

The library provides 4 different error types:

Error Types: - TokenError - Base exception - TokenExpiredError - Token has expired - InvalidTokenError - Token is invalid - PermissionDeniedError - Permission denied

Simple Examples:

from secure_token import (
    SecureTokenManager,
    TokenExpiredError,
    InvalidTokenError,
    PermissionDeniedError
)

manager = SecureTokenManager()

# Example 1: Simple handling
try:
    result = manager.validate_token(token)
    print("Token is valid!")
except TokenExpiredError:
    print("⏱ Token expired - please login again")
except InvalidTokenError:
    print("❌ Token is invalid")
except Exception as e:
    print(f"Error: {e}")

# Example 2: Check permission
try:
    manager.check_permission(token, "admin")
    print("✓ Has admin access")
except PermissionDeniedError:
    print("✗ No admin access")
except TokenExpiredError:
    print("⏱ Token expired")

# Example 3: Safe validation function
def safe_validate(token):
    """Safe validation"""
    try:
        return manager.validate_token(token)
    except TokenExpiredError:
        return {"valid": False, "error": "expired"}
    except InvalidTokenError:
        return {"valid": False, "error": "invalid"}
    except Exception:
        return {"valid": False, "error": "unknown"}

🎨 Complete Example¶

A simple authentication system:

from secure_token import SecureTokenManager

class AuthSystem:
    """Simple authentication system"""

    def __init__(self):
        self.manager = SecureTokenManager()

    def login(self, username, permissions=None):
        """Login user and create token"""
        token = self.manager.generate_token(
            user_id=username,
            permissions=permissions or ["read"],
            expires_in_hours=24
        )
        print(f"✓ {username} logged in")
        return token

    def check_access(self, token, permission):
        """Check access permission"""
        try:
            self.manager.check_permission(token, permission)
            return True
        except:
            return False

    def get_user(self, token):
        """Get user information"""
        try:
            result = self.manager.validate_token(token)
            return result['user_id']
        except:
            return None

# Usage
auth = AuthSystem()

# Login regular user
user_token = auth.login("john", ["read", "write"])

# Login admin
admin_token = auth.login("admin", ["read", "write", "admin"])

# Check access
if auth.check_access(user_token, "write"):
    print("✓ User can write")

if auth.check_access(user_token, "admin"):
    print("✓ User is admin")
else:
    print("✗ User is not admin")

# Get username
username = auth.get_user(user_token)
print(f"Username: {username}")

🔧 Utility Functions¶

generate_secret_key - Generate Secret Key¶

Generates a secure random secret key.

Examples:

from secure_token import generate_secret_key

# Generate 32-character key
key = generate_secret_key(32)
print(key)  # Example: "kJ8mN3qR7sT2vW9yB4xD6zA1cF5gH0iL"

# Generate 16-character key
short_key = generate_secret_key(16)

# Use in settings
from secure_token import Settings, SecureTokenManager

settings = Settings(
    SECRET_KEY=generate_secret_key(32),
    DEFAULT_EXPIRATION_HOURS=24
)
manager = SecureTokenManager(settings_instance=settings)

generate_salt - Generate Salt¶

Generates random salt for enhanced security.

Examples:

from secure_token import generate_salt

# Generate 32-byte salt
salt = generate_salt(32)
print(len(salt))  # 32

# Generate 16-byte salt
small_salt = generate_salt(16)

# Use in settings
from secure_token import Settings, SecureTokenManager

settings = Settings(
    SECRET_KEY="MySecretKey@123",
    SALT=generate_salt(32),
    DEFAULT_EXPIRATION_HOURS=24
)
manager = SecureTokenManager(settings_instance=settings)

✅ Validators¶

validate_permissions - Validate Permissions¶

Validates a list of permissions.

Examples:

from secure_token import validate_permissions

# Example 1: Valid list
try:
    validate_permissions(["read", "write", "admin"])
    print("✓ Permissions are valid")
except Exception as e:
    print(f"✗ Error: {e}")

# Example 2: Invalid list
try:
    validate_permissions(["x"])  # Too short!
except Exception as e:
    print(f"Error: {e}")  # Length must be between 2 and 30

# Example 3: Use in a function
def add_permission(permissions, new_perm):
    """Add new permission"""
    test_list = permissions + [new_perm]
    try:
        validate_permissions(test_list)
        return test_list
    except:
        return permissions  # Return previous list

validate_expires_hours - Validate Expiration Time¶

Validates expiration time (must be between 0 and 8760 hours).

Examples:

from secure_token import validate_expires_hours

# Example 1: Valid times
try:
    validate_expires_hours(24)  # ✓ 24 hours
    validate_expires_hours(168)  # ✓ 1 week
    validate_expires_hours(720)  # ✓ 1 month
    print("✓ Times are valid")
except Exception as e:
    print(f"✗ Error: {e}")

# Example 2: Invalid time
try:
    validate_expires_hours(10000)  # Too much!
except Exception as e:
    print(f"Error: {e}")  # Must be less than 8760

# Example 3: Use in a function
def safe_expiration(hours):
    """Safe expiration setting"""
    try:
        validate_expires_hours(hours)
        return hours
    except:
        return 24  # Default 24 hours

📊 Methods Summary¶

Method	Purpose	Example
`generate_token`	Create token	`manager.generate_token("user_123")`
`validate_token`	Validate token	`manager.validate_token(token)`
`check_permission`	Check permission	`manager.check_permission(token, "admin")`
`refresh_token`	Refresh token	`manager.refresh_token(token)`
`get_token_info`	Get token info	`manager.get_token_info(token)`
`export_config`	Export config	`manager.export_config()`
`generate_secret_key`	Generate key	`generate_secret_key(32)`
`generate_salt`	Generate salt	`generate_salt(32)`

📚 Documentation¶

📖 Complete Documentation¶

For more information:

📋 API Reference - Complete API reference
🎓 Tutorial Guide - Step-by-step guide
🔧 Advanced Examples - Advanced examples with Flask and Django
⚙️ Development Setup - Development environment setup
🧪 Testing Guide - Testing guide

🌐 Online Documentation¶

📖 Full Online Documentation

🤝 Contributing¶

We welcome contributions!

Please see our Contributing Guide for more information.

📄 License¶

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

🔗 Links¶

📦 PyPI: pypi.org/project/secure-token
💻 GitHub: github.com/amirhosein2004/secure-token
📖 Docs: secure-token.readthedocs.io
🐛 Issues: Report Bug

👨‍💻 Author¶

Made with ❤️ by AmirHossein Babaee

Secure Token - Because your application's security matters

⭐ If you find this project useful, don't forget to give it a star!