feat: Add authentication middleware and integration documentation

.env.auth.example

@@ -0,0 +1,53 @@
+# Authentication Configuration Example
+#
+# Copy this file to .env and configure for your environment
+# These settings control JWT and API key authentication
+
+# ========================================
+# JWT Configuration
+# ========================================
+
+# REQUIRED: Secret key for signing JWT tokens
+# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+AUTH_JWT_SECRET_KEY=your-super-secret-key-change-this-in-production
+
+# JWT algorithm (default: HS256)
+AUTH_JWT_ALGORITHM=HS256
+
+# JWT token expiration in minutes (default: 60)
+AUTH_JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60
+
+# JWT issuer (default: contextiq)
+AUTH_JWT_ISSUER=contextiq
+
+# ========================================
+# API Key Configuration
+# ========================================
+
+# Enable API key authentication (default: true)
+AUTH_API_KEY_ENABLED=true
+
+# ========================================
+# Authentication Enforcement
+# ========================================
+
+# Require authentication for all endpoints (default: true)
+# Set to false to disable authentication globally
+AUTH_REQUIRE_AUTH=true
+
+# Comma-separated list of paths exempt from authentication
+# These paths will be accessible without authentication
+AUTH_REQUIRE_AUTH_EXCEPTIONS=/health,/health/live,/health/ready,/docs,/redoc,/openapi.json,/metrics
+
+# ========================================
+# Example API Keys
+# ========================================
+
+# In production, store API keys in a secure database
+# This is just for development/testing
+
+# Example API key (generated): ck_xxxxx...
+# To generate: python -c "from shared.auth.api_key import APIKeyHandler; print(APIKeyHandler().generate_api_key())"
+
+# Example user_id for API key: user_123
+# Example org_id for API key: org_456