orion/docs/guides/user-management.md

Authentication Usage Examples

This document provides practical examples of how to use the authentication system in the Ecommerce Backend API.

Overview

The API uses JWT (JSON Web Token) authentication with the following workflow:

1. Register a new user account
2. Login to receive a JWT token
3. Include the token in the Authorization header for protected endpoints
4. Token expires after 30 minutes (configurable)

Python Examples

Basic Authentication Functions

import requests

# API Base URL
BASE_URL = "http://localhost:8000"

def register_user(email, username, password):
    """Register a new user"""
    response = requests.post(
        f"{BASE_URL}/register",
        json={"email": email, "username": username, "password": password},
    )
    return response.json()

def login_user(username, password):
    """Login and get JWT token"""
    response = requests.post(
        f"{BASE_URL}/login", json={"username": username, "password": password}
    )
    if response.status_code == 200:
        data = response.json()
        return data["access_token"]
    else:
        print(f"Login failed: {response.json()}")
        return None

def get_user_info(token):
    """Get current user info"""
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(f"{BASE_URL}/me", headers=headers)
    return response.json()

Using Protected Endpoints

def get_products(token, skip=0, limit=10):
    """Get products (requires authentication)"""
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(
        f"{BASE_URL}/products?skip={skip}&limit={limit}", headers=headers
    )
    return response.json()

def create_product(token, product_data):
    """Create a new product (requires authentication)"""
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.post(f"{BASE_URL}/products", json=product_data, headers=headers)
    return response.json()

Complete Workflow Example

# Example usage workflow
if __name__ == "__main__":
    # 1. Register a new user
    print("1. Registering new user...")
    try:
        user_result = register_user("test@example.com", "testuser", "password123")
        print(f"User registered: {user_result}")
    except Exception as e:
        print(f"Registration failed: {e}")

    # 2. Login with default admin user
    print("\n2. Logging in as admin...")
    admin_token = login_user("admin", "admin123")
    if admin_token:
        print(f"Admin login successful! Token: {admin_token[:50]}...")

        # 3. Get user info
        print("\n3. Getting admin user info...")
        user_info = get_user_info(admin_token)
        print(f"User info: {user_info}")

        # 4. Create a sample product
        print("\n4. Creating a sample product...")
        sample_product = {
            "marketplace_product_id": "TEST001",
            "title": "Test MarketplaceProduct",
            "description": "A test product for demonstration",
            "price": "19.99",
            "brand": "Test Brand",
            "availability": "in inventory",
        }

        product_result = create_product(admin_token, sample_product)
        print(f"MarketplaceProduct created: {product_result}")

        # 5. Get products list
        print("\n5. Getting products list...")
        products = get_products(admin_token)
        print(f"Products: {products}")

    # 6. Login with regular user
    print("\n6. Logging in as regular user...")
    user_token = login_user("testuser", "password123")
    if user_token:
        print(f"User login successful! Token: {user_token[:50]}...")

        # Regular users can also access protected endpoints
        user_info = get_user_info(user_token)
        print(f"Regular user info: {user_info}")

        products = get_products(user_token, limit=5)
        print(
            f"Products accessible to regular user: {len(products.get('products', []))} products"
        )

    print("\nAuthentication example completed!")

cURL Examples

Register a New User

curl -X POST "http://localhost:8000/register" \
     -H "Content-Type: application/json" \
     -d '{
       "email": "user@example.com", 
       "username": "newuser", 
       "password": "password123"
     }'

Response:

{
  "id": 2,
  "email": "user@example.com",
  "username": "newuser",
  "role": "user",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}

Login (Get JWT Token)

curl -X POST "http://localhost:8000/login" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "admin", 
       "password": "admin123"
     }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 1800,
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "admin",
    "is_active": true
  }
}

Use Token for Protected Endpoints

Get Current User Info

curl -X GET "http://localhost:8000/me" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"

Get Products List

curl -X GET "http://localhost:8000/products" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"

Create a MarketplaceProduct

curl -X POST "http://localhost:8000/products" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE" \
     -H "Content-Type: application/json" \
     -d '{
       "marketplace_product_id": "TEST001", 
       "title": "Test MarketplaceProduct", 
       "description": "A test product for demonstration",
       "price": "19.99",
       "brand": "Test Brand",
       "availability": "in inventory"
     }'

Default Accounts

Admin Account

• Username: admin
• Password: admin123
• Email: admin@example.com
• Role: admin

Security Note: Change the admin password immediately in production environments!

Authentication Headers

All protected endpoints require the JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Error Handling

Common Authentication Errors

Invalid Credentials (Login)

{
  "detail": "Invalid credentials"
}

Missing or Invalid Token

{
  "detail": "Not authenticated"
}

Expired Token

{
  "detail": "Token has expired"
}

Insufficient Permissions

{
  "detail": "Not enough permissions"
}

Error Handling in Python

def safe_api_call(token, endpoint, method="GET", data=None):
    """Make API call with proper error handling"""
    headers = {"Authorization": f"Bearer {token}"}
    
    try:
        if method == "GET":
            response = requests.get(f"{BASE_URL}{endpoint}", headers=headers)
        elif method == "POST":
            response = requests.post(f"{BASE_URL}{endpoint}", json=data, headers=headers)
        
        if response.status_code == 401:
            print("Authentication failed - token may be expired")
            return None
        elif response.status_code == 403:
            print("Access denied - insufficient permissions")
            return None
        elif response.status_code == 200:
            return response.json()
        else:
            print(f"API call failed: {response.status_code} - {response.text}")
            return None
            
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

Best Practices

Token Management

1. Store tokens securely - Don't expose tokens in logs or client-side code
2. Handle token expiration - Implement automatic token refresh or re-login
3. Use HTTPS in production - Never send tokens over unencrypted connections

Password Security

1. Use strong passwords - Minimum 6 characters (configurable)
2. Don't hardcode passwords - Use environment variables or secure configuration
3. Regular password updates - Especially for admin accounts

API Integration

1. Include error handling - Always check response status codes
2. Implement retry logic - Handle temporary network issues
3. Rate limiting awareness - Respect API rate limits

Testing Authentication

You can test the authentication system using the provided Python script or with make commands:

# Run authentication tests
make test-auth

# Run all tests including authentication
make test

Integration with Frontend

JavaScript/TypeScript Example

class APIClient {
    constructor(baseURL = 'http://localhost:8000') {
        this.baseURL = baseURL;
        this.token = localStorage.getItem('jwt_token');
    }

    async login(username, password) {
        const response = await fetch(`${this.baseURL}/login`, {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({username, password})
        });
        
        if (response.ok) {
            const data = await response.json();
            this.token = data.access_token;
            localStorage.setItem('jwt_token', this.token);
            return data;
        } else {
            throw new Error('Login failed');
        }
    }

    async apiCall(endpoint, method = 'GET', data = null) {
        const headers = {
            'Authorization': `Bearer ${this.token}`,
            'Content-Type': 'application/json'
        };

        const config = {method, headers};
        if (data) config.body = JSON.stringify(data);

        const response = await fetch(`${this.baseURL}${endpoint}`, config);
        
        if (response.status === 401) {
            // Token expired, redirect to login
            localStorage.removeItem('jwt_token');
            window.location.href = '/login';
            return;
        }
        
        return response.json();
    }
}

This authentication system provides secure access control for all API endpoints while maintaining ease of use for developers integrating with the system.