Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

Add API keys, analytics, webhooks, and middleware

Juan Denisc5710e88b9d6
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index 329f138f..c9b9bdfc 100644
--- a/backend/app/__init__.py
+++ b/backend/app/__init__.py
@@ -13,6 +13,7 @@ db = SQLAlchemy()
jwt = JWTManager()
migrate = Migrate()
limiter = Limiter(key_func=get_remote_address, default_limits=["100 per minute"])
+# Note: key_func is updated to get_rate_limit_key after app init
socketio = None
# Path to frontend dist folder (relative to backend folder)
@@ -42,7 +43,7 @@ def create_app(config_name=None):
app,
origins=app.config['CORS_ORIGINS'],
supports_credentials=True,
- allow_headers=['Content-Type', 'Authorization', 'X-Requested-With'],
+ allow_headers=['Content-Type', 'Authorization', 'X-Requested-With', 'X-API-Key'],
methods=['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH']
)
@@ -50,6 +51,19 @@ def create_app(config_name=None):
from app.middleware.security import register_security_headers
register_security_headers(app)
+ # Register API key authentication middleware
+ from app.middleware.api_key_auth import register_api_key_auth
+ register_api_key_auth(app)
+
+ # Register API analytics middleware
+ from app.middleware.api_analytics import register_api_analytics
+ register_api_analytics(app)
+
+ # Update rate limiter with custom key function
+ from app.middleware.rate_limit import get_rate_limit_key, register_rate_limit_headers
+ limiter._key_func = get_rate_limit_key
+ register_rate_limit_headers(app)
+
# Initialize SocketIO
from app.sockets import init_socketio
socketio = init_socketio(app)
@@ -178,6 +192,16 @@ def create_app(config_name=None):
from app.api.migrations import migrations_bp
app.register_blueprint(migrations_bp, url_prefix='/api/v1/migrations')
+ # Register blueprints - API Enhancements
+ from app.api.api_keys import api_keys_bp
+ from app.api.api_analytics import api_analytics_bp
+ from app.api.event_subscriptions import event_subscriptions_bp
+ from app.api.docs import docs_bp
+ app.register_blueprint(api_keys_bp, url_prefix='/api/v1/api-keys')
+ app.register_blueprint(api_analytics_bp, url_prefix='/api/v1/api-analytics')
+ app.register_blueprint(event_subscriptions_bp, url_prefix='/api/v1/event-subscriptions')
+ app.register_blueprint(docs_bp, url_prefix='/api/v1/docs')
+
# Register blueprints - Admin (User Management, Settings, Audit Logs)
from app.api.admin import admin_bp
app.register_blueprint(admin_bp, url_prefix='/api/v1/admin')
@@ -212,6 +236,13 @@ def create_app(config_name=None):
# Start auto-sync scheduler for WordPress environments
_start_auto_sync_scheduler(app)
+ # Start API analytics flush thread
+ from app.middleware.api_analytics import start_analytics_flush_thread
+ start_analytics_flush_thread(app)
+
+ # Start hourly analytics aggregation and event retry threads
+ _start_api_background_threads(app)
+
# Serve frontend for root path
@app.route('/')
def serve_index():
@@ -312,3 +343,39 @@ def _check_auto_sync_schedules(logger):
)
except Exception as e:
logger.error(f'Auto-sync check failed for site {site.id}: {e}')
+
+
+_api_bg_thread = None
+
+
+def _start_api_background_threads(app):
+ """Start background threads for API analytics aggregation and event delivery retry."""
+ global _api_bg_thread
+ if _api_bg_thread is not None:
+ return
+
+ import threading
+ import time
+ import logging
+
+ logger = logging.getLogger(__name__)
+
+ def api_bg_loop():
+ while True:
+ try:
+ time.sleep(3600) # Run hourly
+ with app.app_context():
+ from app.services.api_analytics_service import ApiAnalyticsService
+ ApiAnalyticsService.aggregate_hourly()
+
+ from app.services.event_service import EventService
+ EventService.retry_failed()
+ except Exception as e:
+ logger.error(f'API background thread error: {e}')
+
+ _api_bg_thread = threading.Thread(
+ target=api_bg_loop,
+ daemon=True,
+ name='api-background'
+ )
+ _api_bg_thread.start()
diff --git a/backend/app/api/api_analytics.py b/backend/app/api/api_analytics.py
new file mode 100644
index 00000000..612dac59
--- /dev/null
+++ b/backend/app/api/api_analytics.py
@@ -0,0 +1,59 @@
+"""API analytics endpoints."""
+from flask import Blueprint, jsonify, request
+from app.middleware.rbac import admin_required, get_current_user
+from app.services.api_analytics_service import ApiAnalyticsService
+from app.services.api_key_service import ApiKeyService
+
+api_analytics_bp = Blueprint('api_analytics', __name__)
+
+
+@api_analytics_bp.route('/overview', methods=['GET'])
+@admin_required
+def overview():
+ """Get API usage overview."""
+ period = request.args.get('period', '24h')
+ return jsonify(ApiAnalyticsService.get_overview(period))
+
+
+@api_analytics_bp.route('/endpoints', methods=['GET'])
+@admin_required
+def endpoints():
+ """Get top endpoints by usage."""
+ period = request.args.get('period', '24h')
+ limit = request.args.get('limit', 20, type=int)
+ return jsonify({'endpoints': ApiAnalyticsService.get_endpoint_stats(period, limit)})
+
+
+@api_analytics_bp.route('/errors', methods=['GET'])
+@admin_required
+def errors():
+ """Get error breakdown."""
+ period = request.args.get('period', '24h')
+ return jsonify({'errors': ApiAnalyticsService.get_error_stats(period)})
+
+
+@api_analytics_bp.route('/timeseries', methods=['GET'])
+@admin_required
+def timeseries():
+ """Get time series data for charts."""
+ period = request.args.get('period', '24h')
+ interval = request.args.get('interval', 'hour')
+ return jsonify({'data': ApiAnalyticsService.get_time_series(period, interval)})
+
+
+@api_analytics_bp.route('/keys/<int:key_id>/usage', methods=['GET'])
+@admin_required
+def key_usage(key_id):
+ """Get usage stats for a specific API key."""
+ period = request.args.get('period', '24h')
+
+ # Allow key owners to view their own usage
+ user = get_current_user()
+ api_key = ApiKeyService.get_key(key_id)
+ if not api_key:
+ return jsonify({'error': 'API key not found'}), 404
+
+ if not user.is_admin and api_key.user_id != user.id:
+ return jsonify({'error': 'Access denied'}), 403
+
+ return jsonify(ApiAnalyticsService.get_key_usage(key_id, period))
diff --git a/backend/app/api/api_keys.py b/backend/app/api/api_keys.py
new file mode 100644
index 00000000..caf1af01
--- /dev/null
+++ b/backend/app/api/api_keys.py
@@ -0,0 +1,150 @@
+"""API Key management endpoints."""
+from datetime import datetime
+from flask import Blueprint, jsonify, request
+from flask_jwt_extended import jwt_required, get_jwt_identity
+from app.middleware.rbac import get_current_user
+from app.services.api_key_service import ApiKeyService
+from app.services.audit_service import AuditService
+from app.models.audit_log import AuditLog
+
+api_keys_bp = Blueprint('api_keys', __name__)
+
+
+@api_keys_bp.route('/', methods=['GET'])
+@jwt_required()
+def list_keys():
+ """List the current user's API keys."""
+ user = get_current_user()
+ if not user or not user.is_developer:
+ return jsonify({'error': 'Developer access required'}), 403
+
+ keys = ApiKeyService.list_keys(user.id)
+ return jsonify({'api_keys': [k.to_dict() for k in keys]})
+
+
+@api_keys_bp.route('/', methods=['POST'])
+@jwt_required()
+def create_key():
+ """Create a new API key."""
+ user = get_current_user()
+ if not user or not user.is_developer:
+ return jsonify({'error': 'Developer access required'}), 403
+
+ data = request.get_json() or {}
+ name = data.get('name')
+ if not name:
+ return jsonify({'error': 'Name is required'}), 400
+
+ scopes = data.get('scopes')
+ tier = data.get('tier', 'standard')
+ expires_at = None
+ if data.get('expires_at'):
+ try:
+ expires_at = datetime.fromisoformat(data['expires_at'].replace('Z', '+00:00'))
+ except (ValueError, AttributeError):
+ return jsonify({'error': 'Invalid expires_at format'}), 400
+
+ api_key, raw_key = ApiKeyService.create_key(
+ user_id=user.id,
+ name=name,
+ scopes=scopes,
+ tier=tier,
+ expires_at=expires_at,
+ )
+
+ AuditService.log(
+ AuditLog.ACTION_API_KEY_CREATE,
+ user_id=user.id,
+ target_type='api_key',
+ target_id=api_key.id,
+ details={'name': name, 'tier': tier}
+ )
+
+ result = api_key.to_dict()
+ result['raw_key'] = raw_key # Only exposed once at creation
+ return jsonify(result), 201
+
+
+@api_keys_bp.route('/<int:key_id>', methods=['GET'])
+@jwt_required()
+def get_key(key_id):
+ """Get API key details."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ api_key = ApiKeyService.get_key(key_id, user.id)
+ if not api_key:
+ return jsonify({'error': 'API key not found'}), 404
+
+ return jsonify(api_key.to_dict())
+
+
+@api_keys_bp.route('/<int:key_id>', methods=['PUT'])
+@jwt_required()
+def update_key(key_id):
+ """Update API key metadata."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ data = request.get_json() or {}
+ api_key = ApiKeyService.update_key(
+ key_id=key_id,
+ user_id=user.id,
+ name=data.get('name'),
+ scopes=data.get('scopes'),
+ tier=data.get('tier'),
+ )
+ if not api_key:
+ return jsonify({'error': 'API key not found'}), 404
+
+ return jsonify(api_key.to_dict())
+
+
+@api_keys_bp.route('/<int:key_id>', methods=['DELETE'])
+@jwt_required()
+def revoke_key(key_id):
+ """Revoke an API key."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ api_key = ApiKeyService.revoke_key(key_id, user.id)
+ if not api_key:
+ return jsonify({'error': 'API key not found'}), 404
+
+ AuditService.log(
+ AuditLog.ACTION_API_KEY_REVOKE,
+ user_id=user.id,
+ target_type='api_key',
+ target_id=key_id,
+ details={'name': api_key.name}
+ )
+
+ return jsonify({'message': 'API key revoked'})
+
+
+@api_keys_bp.route('/<int:key_id>/rotate', methods=['POST'])
+@jwt_required()
+def rotate_key(key_id):
+ """Rotate an API key (revoke + recreate with same config)."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ new_key, raw_key = ApiKeyService.rotate_key(key_id, user.id)
+ if not new_key:
+ return jsonify({'error': 'API key not found'}), 404
+
+ AuditService.log(
+ AuditLog.ACTION_API_KEY_ROTATE,
+ user_id=user.id,
+ target_type='api_key',
+ target_id=new_key.id,
+ details={'old_key_id': key_id, 'name': new_key.name}
+ )
+
+ result = new_key.to_dict()
+ result['raw_key'] = raw_key
+ return jsonify(result)
diff --git a/backend/app/api/docs.py b/backend/app/api/docs.py
new file mode 100644
index 00000000..86e85ee6
--- /dev/null
+++ b/backend/app/api/docs.py
@@ -0,0 +1,47 @@
+"""OpenAPI/Swagger documentation endpoints."""
+from flask import Blueprint, jsonify
+
+docs_bp = Blueprint('docs', __name__)
+
+
+@docs_bp.route('/', methods=['GET'])
+def swagger_ui():
+ """Serve Swagger UI."""
+ html = '''<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <title>ServerKit API Documentation</title>
+ <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+ <style>
+ body { margin: 0; padding: 0; }
+ .swagger-ui .topbar { display: none; }
+ </style>
+</head>
+<body>
+ <div id="swagger-ui"></div>
+ <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+ <script>
+ SwaggerUIBundle({
+ url: './openapi.json',
+ dom_id: '#swagger-ui',
+ presets: [
+ SwaggerUIBundle.presets.apis,
+ SwaggerUIBundle.SwaggerUIStandalonePreset
+ ],
+ layout: 'BaseLayout',
+ deepLinking: true,
+ defaultModelsExpandDepth: -1,
+ });
+ </script>
+</body>
+</html>'''
+ return html, 200, {'Content-Type': 'text/html'}
+
+
+@docs_bp.route('/openapi.json', methods=['GET'])
+def openapi_spec():
+ """Return the generated OpenAPI specification."""
+ from app.services.openapi_service import OpenAPIService
+ spec = OpenAPIService.generate_spec()
+ return jsonify(spec)
diff --git a/backend/app/api/event_subscriptions.py b/backend/app/api/event_subscriptions.py
new file mode 100644
index 00000000..c510e878
--- /dev/null
+++ b/backend/app/api/event_subscriptions.py
@@ -0,0 +1,228 @@
+"""Webhook event subscription endpoints."""
+from flask import Blueprint, jsonify, request
+from flask_jwt_extended import jwt_required, get_jwt_identity
+from app.middleware.rbac import get_current_user, auth_required
+from app.models.event_subscription import EventSubscription
+from app.services.event_service import EventService
+from app import db
+
+event_subscriptions_bp = Blueprint('event_subscriptions', __name__)
+
+
+@event_subscriptions_bp.route('/', methods=['GET'])
+@jwt_required()
+def list_subscriptions():
+ """List webhook subscriptions."""
+ user = get_current_user()
+ if not user or not user.is_developer:
+ return jsonify({'error': 'Developer access required'}), 403
+
+ if user.is_admin:
+ subs = EventSubscription.query.order_by(EventSubscription.created_at.desc()).all()
+ else:
+ subs = EventSubscription.query.filter_by(user_id=user.id).order_by(
+ EventSubscription.created_at.desc()
+ ).all()
+
+ return jsonify({'subscriptions': [s.to_dict() for s in subs]})
+
+
+@event_subscriptions_bp.route('/', methods=['POST'])
+@jwt_required()
+def create_subscription():
+ """Create a new webhook subscription."""
+ user = get_current_user()
+ if not user or not user.is_developer:
+ return jsonify({'error': 'Developer access required'}), 403
+
+ data = request.get_json() or {}
+ name = data.get('name')
+ url = data.get('url')
+ events = data.get('events', [])
+
+ if not name or not url:
+ return jsonify({'error': 'Name and URL are required'}), 400
+ if not events:
+ return jsonify({'error': 'At least one event type is required'}), 400
+
+ sub = EventSubscription(
+ user_id=user.id,
+ name=name,
+ url=url,
+ retry_count=data.get('retry_count', 3),
+ timeout_seconds=data.get('timeout_seconds', 10),
+ )
+ sub.set_events(events)
+
+ if data.get('generate_secret', True):
+ sub.secret = EventSubscription.generate_secret()
+
+ custom_headers = data.get('headers')
+ if custom_headers:
+ sub.set_headers(custom_headers)
+
+ db.session.add(sub)
+ db.session.commit()
+
+ result = sub.to_dict()
+ # Expose secret once at creation
+ if sub.secret:
+ result['secret'] = sub.secret
+
+ return jsonify(result), 201
+
+
+@event_subscriptions_bp.route('/events', methods=['GET'])
+@auth_required()
+def list_events():
+ """List available event types."""
+ return jsonify({'events': EventService.get_available_events()})
+
+
+@event_subscriptions_bp.route('/<int:sub_id>', methods=['GET'])
+@jwt_required()
+def get_subscription(sub_id):
+ """Get subscription details."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ sub = EventSubscription.query.get(sub_id)
+ if not sub:
+ return jsonify({'error': 'Subscription not found'}), 404
+ if not user.is_admin and sub.user_id != user.id:
+ return jsonify({'error': 'Access denied'}), 403
+
+ return jsonify(sub.to_dict())
+
+
+@event_subscriptions_bp.route('/<int:sub_id>', methods=['PUT'])
+@jwt_required()
+def update_subscription(sub_id):
+ """Update a webhook subscription."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ sub = EventSubscription.query.get(sub_id)
+ if not sub:
+ return jsonify({'error': 'Subscription not found'}), 404
+ if not user.is_admin and sub.user_id != user.id:
+ return jsonify({'error': 'Access denied'}), 403
+
+ data = request.get_json() or {}
+
+ if 'name' in data:
+ sub.name = data['name']
+ if 'url' in data:
+ sub.url = data['url']
+ if 'events' in data:
+ sub.set_events(data['events'])
+ if 'is_active' in data:
+ sub.is_active = data['is_active']
+ if 'headers' in data:
+ sub.set_headers(data['headers'])
+ if 'retry_count' in data:
+ sub.retry_count = data['retry_count']
+ if 'timeout_seconds' in data:
+ sub.timeout_seconds = data['timeout_seconds']
+
+ db.session.commit()
+ return jsonify(sub.to_dict())
+
+
+@event_subscriptions_bp.route('/<int:sub_id>', methods=['DELETE'])
+@jwt_required()
+def delete_subscription(sub_id):
+ """Delete a webhook subscription."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ sub = EventSubscription.query.get(sub_id)
+ if not sub:
+ return jsonify({'error': 'Subscription not found'}), 404
+ if not user.is_admin and sub.user_id != user.id:
+ return jsonify({'error': 'Access denied'}), 403
+
+ db.session.delete(sub)
+ db.session.commit()
+ return jsonify({'message': 'Subscription deleted'})
+
+
+@event_subscriptions_bp.route('/<int:sub_id>/test', methods=['POST'])
+@jwt_required()
+def test_subscription(sub_id):
+ """Send a test event to a subscription."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ sub = EventSubscription.query.get(sub_id)
+ if not sub:
+ return jsonify({'error': 'Subscription not found'}), 404
+ if not user.is_admin and sub.user_id != user.id:
+ return jsonify({'error': 'Access denied'}), 403
+
+ delivery = EventService.send_test(sub_id)
+ if not delivery:
+ return jsonify({'error': 'Failed to send test'}), 500
+
+ return jsonify(delivery.to_dict())
+
+
+@event_subscriptions_bp.route('/<int:sub_id>/deliveries', methods=['GET'])
+@jwt_required()
+def list_deliveries(sub_id):
+ """Get delivery history for a subscription."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ sub = EventSubscription.query.get(sub_id)
+ if not sub:
+ return jsonify({'error': 'Subscription not found'}), 404
+ if not user.is_admin and sub.user_id != user.id:
+ return jsonify({'error': 'Access denied'}), 403
+
+ page = request.args.get('page', 1, type=int)
+ per_page = request.args.get('per_page', 50, type=int)
+
+ pagination = EventService.get_deliveries(sub_id, page, per_page)
+ return jsonify({
+ 'deliveries': [d.to_dict() for d in pagination.items],
+ 'total': pagination.total,
+ 'page': page,
+ 'per_page': per_page,
+ 'pages': pagination.pages,
+ })
+
+
+@event_subscriptions_bp.route('/<int:sub_id>/deliveries/<int:delivery_id>/retry', methods=['POST'])
+@jwt_required()
+def retry_delivery(sub_id, delivery_id):
+ """Retry a failed delivery."""
+ user = get_current_user()
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+
+ sub = EventSubscription.query.get(sub_id)
+ if not sub:
+ return jsonify({'error': 'Subscription not found'}), 404
+ if not user.is_admin and sub.user_id != user.id:
+ return jsonify({'error': 'Access denied'}), 403
+
+ from app.models.event_subscription import EventDelivery
+ delivery = EventDelivery.query.filter_by(id=delivery_id, subscription_id=sub_id).first()
+ if not delivery:
+ return jsonify({'error': 'Delivery not found'}), 404
+
+ delivery.status = EventDelivery.STATUS_PENDING
+ delivery.next_retry_at = None
+ db.session.commit()
+
+ EventService.deliver(delivery_id)
+
+ # Refresh
+ delivery = EventDelivery.query.get(delivery_id)
+ return jsonify(delivery.to_dict())
diff --git a/backend/app/middleware/api_analytics.py b/backend/app/middleware/api_analytics.py
new file mode 100644
index 00000000..aee428d9
--- /dev/null
+++ b/backend/app/middleware/api_analytics.py
@@ -0,0 +1,115 @@
+"""API analytics middleware for logging request metrics."""
+import time
+import threading
+import logging
+from flask import g, request
+
+logger = logging.getLogger(__name__)
+
+# Buffer for batch inserts
+_log_buffer = []
+_buffer_lock = threading.Lock()
+
+
+def register_api_analytics(app):
+ """Register before/after request handlers for API analytics."""
+
+ @app.before_request
+ def record_request_start():
+ """Record request start time."""
+ if request.path.startswith('/api/'):
+ g.request_start_time = time.time()
+
+ @app.after_request
+ def record_request_metrics(response):
+ """Log API request metrics."""
+ if not request.path.startswith('/api/'):
+ return response
+
+ start_time = getattr(g, 'request_start_time', None)
+ if start_time is None:
+ return response
+
+ elapsed_ms = (time.time() - start_time) * 1000
+
+ api_key = getattr(g, 'api_key', None)
+ api_key_user = getattr(g, 'api_key_user', None)
+
+ # Get user_id from API key or JWT
+ user_id = None
+ if api_key_user:
+ user_id = api_key_user.id
+ else:
+ try:
+ from flask_jwt_extended import get_jwt_identity
+ user_id = get_jwt_identity()
+ except Exception:
+ pass
+
+ ip_address = request.remote_addr
+ if request.headers.get('X-Forwarded-For'):
+ ip_address = request.headers.get('X-Forwarded-For').split(',')[0].strip()
+ elif request.headers.get('X-Real-IP'):
+ ip_address = request.headers.get('X-Real-IP')
+
+ log_entry = {
+ 'api_key_id': api_key.id if api_key else None,
+ 'user_id': user_id,
+ 'method': request.method,
+ 'endpoint': request.path,
+ 'blueprint': request.blueprints[0] if request.blueprints else None,
+ 'status_code': response.status_code,
+ 'response_time_ms': round(elapsed_ms, 2),
+ 'ip_address': ip_address,
+ 'user_agent': (request.headers.get('User-Agent') or '')[:500],
+ 'request_size': request.content_length or 0,
+ 'response_size': response.content_length or 0,
+ }
+
+ with _buffer_lock:
+ _log_buffer.append(log_entry)
+
+ return response
+
+
+def start_analytics_flush_thread(app):
+ """Start background thread to flush analytics buffer to DB."""
+
+ def flush_loop():
+ while True:
+ time.sleep(5)
+ try:
+ _flush_buffer(app)
+ except Exception as e:
+ logger.error(f'Analytics flush error: {e}')
+
+ thread = threading.Thread(
+ target=flush_loop,
+ daemon=True,
+ name='api-analytics-flush'
+ )
+ thread.start()
+ return thread
+
+
+def _flush_buffer(app):
+ """Flush buffered log entries to the database."""
+ with _buffer_lock:
+ if not _log_buffer:
+ return
+ entries = _log_buffer.copy()
+ _log_buffer.clear()
+
+ with app.app_context():
+ from app import db
+ from app.models.api_usage import ApiUsageLog
+
+ for entry in entries:
+ log = ApiUsageLog(**entry)
+ db.session.add(log)
+
+ try:
+ db.session.commit()
+ except Exception as e:
+ db.session.rollback()
+ logger.error(f'Failed to flush analytics: {e}')
diff --git a/backend/app/middleware/api_key_auth.py b/backend/app/middleware/api_key_auth.py
new file mode 100644
index 00000000..64601885
--- /dev/null
+++ b/backend/app/middleware/api_key_auth.py
@@ -0,0 +1,36 @@
+"""API Key authentication middleware."""
+from flask import g, request, jsonify
+
+
+def register_api_key_auth(app):
+ """Register API key authentication as a before_request handler."""
+
+ @app.before_request
+ def authenticate_api_key():
+ """Check for X-API-Key header and validate."""
+ api_key_header = request.headers.get('X-API-Key')
+
+ if not api_key_header:
+ return # No API key provided, fall through to JWT auth
+
+ from app.services.api_key_service import ApiKeyService
+ api_key = ApiKeyService.validate_key(api_key_header)
+
+ if not api_key:
+ return jsonify({'error': 'Invalid or expired API key'}), 401
+
+ # Record usage
+ ip_address = request.remote_addr
+ if request.headers.get('X-Forwarded-For'):
+ ip_address = request.headers.get('X-Forwarded-For').split(',')[0].strip()
+ elif request.headers.get('X-Real-IP'):
+ ip_address = request.headers.get('X-Real-IP')
+
+ api_key.record_usage(ip_address)
+
+ from app import db
+ db.session.commit()
+
+ # Store in g for downstream use
+ g.api_key = api_key
+ g.api_key_user = api_key.user
diff --git a/backend/app/middleware/rate_limit.py b/backend/app/middleware/rate_limit.py
new file mode 100644
index 00000000..111ffbb6
--- /dev/null
+++ b/backend/app/middleware/rate_limit.py
@@ -0,0 +1,86 @@
+"""Enhanced rate limiting with per-tier limits and response headers."""
+from flask import g, request
+
+
+def get_rate_limit_key():
+ """Custom key function for rate limiting based on auth context."""
+ # API key auth
+ api_key = getattr(g, 'api_key', None)
+ if api_key:
+ return f'apikey:{api_key.id}'
+
+ # JWT auth - try to get user id
+ try:
+ from flask_jwt_extended import get_jwt_identity
+ user_id = get_jwt_identity()
+ if user_id:
+ return f'user:{user_id}'
+ except Exception:
+ pass
+
+ # Fall back to IP
+ ip = request.remote_addr
+ if request.headers.get('X-Forwarded-For'):
+ ip = request.headers.get('X-Forwarded-For').split(',')[0].strip()
+ elif request.headers.get('X-Real-IP'):
+ ip = request.headers.get('X-Real-IP')
+ return f'ip:{ip}'
+
+
+def get_dynamic_limit():
+ """Return rate limit string based on auth context tier."""
+ from app.services.settings_service import SettingsService
+
+ # API key tier
+ api_key = getattr(g, 'api_key', None)
+ if api_key:
+ tier = api_key.tier or 'standard'
+ setting_key = f'rate_limit_{tier}'
+ return SettingsService.get(setting_key, _default_for_tier(tier))
+
+ # Authenticated user
+ api_key_user = getattr(g, 'api_key_user', None)
+ if api_key_user:
+ return SettingsService.get('rate_limit_standard', '100 per minute')
+
+ try:
+ from flask_jwt_extended import get_jwt_identity
+ user_id = get_jwt_identity()
+ if user_id:
+ return SettingsService.get('rate_limit_standard', '100 per minute')
+ except Exception:
+ pass
+
+ # Unauthenticated
+ return SettingsService.get('rate_limit_unauthenticated', '30 per minute')
+
+
+def _default_for_tier(tier):
+ """Return default rate limit for a tier."""
+ defaults = {
+ 'standard': '100 per minute',
+ 'elevated': '500 per minute',
+ 'unlimited': '5000 per minute',
+ }
+ return defaults.get(tier, '100 per minute')
+
+
+def register_rate_limit_headers(app):
+ """Register after_request handler to add rate limit headers."""
+
+ @app.after_request
+ def add_rate_limit_headers(response):
+ # Flask-Limiter adds these headers automatically when configured,
+ # but we ensure they are present with standard names
+ limit = response.headers.get('X-RateLimit-Limit')
+ remaining = response.headers.get('X-RateLimit-Remaining')
+ reset = response.headers.get('X-RateLimit-Reset')
+
+ if limit:
+ response.headers['X-RateLimit-Limit'] = limit
+ if remaining:
+ response.headers['X-RateLimit-Remaining'] = remaining
+ if reset:
+ response.headers['X-RateLimit-Reset'] = reset
+
+ return response
diff --git a/backend/app/middleware/rbac.py b/backend/app/middleware/rbac.py
index deb2bf63..2088644d 100644
--- a/backend/app/middleware/rbac.py
+++ b/backend/app/middleware/rbac.py
@@ -1,18 +1,42 @@
"""Role-Based Access Control middleware and decorators."""
from functools import wraps
-from flask import jsonify
-from flask_jwt_extended import jwt_required, get_jwt_identity
+from flask import g, jsonify
+from flask_jwt_extended import jwt_required, get_jwt_identity, verify_jwt_in_request
from app.models import User
def get_current_user():
- """Get the current authenticated user."""
+ """Get the current authenticated user (via API key or JWT)."""
+ # Check API key auth first
+ api_key_user = getattr(g, 'api_key_user', None)
+ if api_key_user:
+ return api_key_user
+
+ # Fall back to JWT
user_id = get_jwt_identity()
if user_id:
return User.query.get(user_id)
return None
+def auth_required():
+ """
+ Decorator that accepts either API key or JWT authentication.
+ Use this instead of @jwt_required() to support both auth methods.
+ """
+ def decorator(fn):
+ @wraps(fn)
+ def wrapper(*args, **kwargs):
+ # If API key already authenticated via middleware, proceed
+ if getattr(g, 'api_key_user', None):
+ return fn(*args, **kwargs)
+ # Otherwise require JWT
+ verify_jwt_in_request()
+ return fn(*args, **kwargs)
+ return wrapper
+ return decorator
+
+
def require_role(*allowed_roles):
"""
Decorator that requires the user to have one of the specified roles.
@@ -24,7 +48,7 @@ def require_role(*allowed_roles):
"""
def decorator(fn):
@wraps(fn)
- @jwt_required()
+ @auth_required()
def wrapper(*args, **kwargs):
user = get_current_user()
if not user:
@@ -48,7 +72,7 @@ def admin_required(fn):
...
"""
@wraps(fn)
- @jwt_required()
+ @auth_required()
def wrapper(*args, **kwargs):
user = get_current_user()
if not user:
@@ -71,7 +95,7 @@ def developer_required(fn):
...
"""
@wraps(fn)
- @jwt_required()
+ @auth_required()
def wrapper(*args, **kwargs):
user = get_current_user()
if not user:
@@ -95,7 +119,7 @@ def viewer_required(fn):
...
"""
@wraps(fn)
- @jwt_required()
+ @auth_required()
def wrapper(*args, **kwargs):
user = get_current_user()
if not user:
diff --git a/backend/app/middleware/security.py b/backend/app/middleware/security.py
index 44780d3b..a5303ac3 100644
--- a/backend/app/middleware/security.py
+++ b/backend/app/middleware/security.py
@@ -23,8 +23,8 @@ def register_security_headers(app: Flask):
# Content Security Policy
csp_directives = [
"default-src 'self'",
- "script-src 'self' 'unsafe-inline' 'unsafe-eval'",
- "style-src 'self' 'unsafe-inline'",
+ "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://unpkg.com",
+ "style-src 'self' 'unsafe-inline' https://unpkg.com",
"img-src 'self' data: https:",
"font-src 'self'",
"connect-src 'self' ws: wss:",
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 1458324a..2a4219db 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -17,6 +17,9 @@ from app.models.promotion_job import PromotionJob
from app.models.sanitization_profile import SanitizationProfile
from app.models.email_account import EmailAccount
from app.models.oauth_identity import OAuthIdentity
+from app.models.api_key import ApiKey
+from app.models.api_usage import ApiUsageLog, ApiUsageSummary
+from app.models.event_subscription import EventSubscription, EventDelivery
__all__ = [
'User', 'Application', 'Domain', 'EnvironmentVariable', 'EnvironmentVariableHistory',
@@ -25,5 +28,6 @@ __all__ = [
'Server', 'ServerGroup', 'ServerMetrics', 'ServerCommand', 'AgentSession', 'SecurityAlert',
'WordPressSite', 'DatabaseSnapshot', 'SyncJob',
'EnvironmentActivity', 'PromotionJob', 'SanitizationProfile', 'EmailAccount',
- 'OAuthIdentity'
+ 'OAuthIdentity', 'ApiKey', 'ApiUsageLog', 'ApiUsageSummary',
+ 'EventSubscription', 'EventDelivery'
]
diff --git a/backend/app/models/api_key.py b/backend/app/models/api_key.py
new file mode 100644
index 00000000..4ece9594
--- /dev/null
+++ b/backend/app/models/api_key.py
@@ -0,0 +1,113 @@
+"""API Key model for programmatic API access."""
+from datetime import datetime
+from app import db
+import hashlib
+import json
+import secrets
+
+
+class ApiKey(db.Model):
+ """API key for programmatic access to the ServerKit API."""
+ __tablename__ = 'api_keys'
+
+ id = db.Column(db.Integer, primary_key=True)
+ user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False)
+ name = db.Column(db.String(100), nullable=False)
+ key_prefix = db.Column(db.String(8), nullable=False)
+ key_hash = db.Column(db.String(256), unique=True, nullable=False)
+ scopes = db.Column(db.Text, nullable=True) # JSON array
+ tier = db.Column(db.String(20), default='standard') # standard | elevated | unlimited
+ is_active = db.Column(db.Boolean, default=True)
+ expires_at = db.Column(db.DateTime, nullable=True)
+ last_used_at = db.Column(db.DateTime, nullable=True)
+ last_used_ip = db.Column(db.String(45), nullable=True)
+ usage_count = db.Column(db.Integer, default=0)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ revoked_at = db.Column(db.DateTime, nullable=True)
+
+ user = db.relationship('User', foreign_keys=[user_id])
+
+ TIER_STANDARD = 'standard'
+ TIER_ELEVATED = 'elevated'
+ TIER_UNLIMITED = 'unlimited'
+ VALID_TIERS = [TIER_STANDARD, TIER_ELEVATED, TIER_UNLIMITED]
+
+ @staticmethod
+ def generate_key():
+ """Generate a new API key. Returns (raw_key, prefix, hash)."""
+ raw = 'sk_' + secrets.token_hex(20)
+ prefix = raw[:8]
+ key_hash = hashlib.sha256(raw.encode()).hexdigest()
+ return raw, prefix, key_hash
+
+ @staticmethod
+ def hash_key(raw_key):
+ """Hash a raw API key."""
+ return hashlib.sha256(raw_key.encode()).hexdigest()
+
+ def get_scopes(self):
+ """Return parsed scopes list."""
+ if self.scopes:
+ try:
+ return json.loads(self.scopes)
+ except (json.JSONDecodeError, TypeError):
+ return []
+ return []
+
+ def set_scopes(self, scopes_list):
+ """Set scopes from a list."""
+ if scopes_list:
+ self.scopes = json.dumps(scopes_list)
+ else:
+ self.scopes = None
+
+ def is_expired(self):
+ """Check if the key has expired."""
+ if self.expires_at is None:
+ return False
+ return datetime.utcnow() > self.expires_at
+
+ def is_valid(self):
+ """Check if the key is active and not expired or revoked."""
+ return self.is_active and not self.is_expired() and self.revoked_at is None
+
+ def has_scope(self, required_scope):
+ """Check if this key has the required scope."""
+ scopes = self.get_scopes()
+ if not scopes or '*' in scopes:
+ return True
+ if required_scope in scopes:
+ return True
+ # Check wildcard resource match (e.g. 'apps:*' matches 'apps:read')
+ resource = required_scope.split(':')[0] if ':' in required_scope else required_scope
+ if f'{resource}:*' in scopes:
+ return True
+ return False
+
+ def record_usage(self, ip_address=None):
+ """Record a usage of this key."""
+ self.last_used_at = datetime.utcnow()
+ self.usage_count = (self.usage_count or 0) + 1
+ if ip_address:
+ self.last_used_ip = ip_address
+
+ def to_dict(self):
+ """Serialize key info (never expose hash)."""
+ return {
+ 'id': self.id,
+ 'user_id': self.user_id,
+ 'name': self.name,
+ 'key_prefix': self.key_prefix,
+ 'scopes': self.get_scopes(),
+ 'tier': self.tier,
+ 'is_active': self.is_active,
+ 'expires_at': self.expires_at.isoformat() if self.expires_at else None,
+ 'last_used_at': self.last_used_at.isoformat() if self.last_used_at else None,
+ 'last_used_ip': self.last_used_ip,
+ 'usage_count': self.usage_count,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'revoked_at': self.revoked_at.isoformat() if self.revoked_at else None,
+ }
+
+ def __repr__(self):
+ return f'<ApiKey {self.key_prefix}... ({self.name})>'
diff --git a/backend/app/models/api_usage.py b/backend/app/models/api_usage.py
new file mode 100644
index 00000000..e7461787
--- /dev/null
+++ b/backend/app/models/api_usage.py
@@ -0,0 +1,68 @@
+"""API usage tracking models."""
+from datetime import datetime
+from app import db
+
+
+class ApiUsageLog(db.Model):
+ """Raw API usage log for every request."""
+ __tablename__ = 'api_usage_logs'
+
+ id = db.Column(db.Integer, primary_key=True)
+ api_key_id = db.Column(db.Integer, db.ForeignKey('api_keys.id'), nullable=True)
+ user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=True)
+ method = db.Column(db.String(10), nullable=False)
+ endpoint = db.Column(db.String(500), nullable=False)
+ blueprint = db.Column(db.String(100), nullable=True)
+ status_code = db.Column(db.Integer, nullable=False)
+ response_time_ms = db.Column(db.Float, nullable=True)
+ ip_address = db.Column(db.String(45), nullable=True)
+ user_agent = db.Column(db.String(500), nullable=True)
+ request_size = db.Column(db.Integer, nullable=True)
+ response_size = db.Column(db.Integer, nullable=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'api_key_id': self.api_key_id,
+ 'user_id': self.user_id,
+ 'method': self.method,
+ 'endpoint': self.endpoint,
+ 'blueprint': self.blueprint,
+ 'status_code': self.status_code,
+ 'response_time_ms': self.response_time_ms,
+ 'ip_address': self.ip_address,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ }
+
+
+class ApiUsageSummary(db.Model):
+ """Aggregated API usage summary per hour."""
+ __tablename__ = 'api_usage_summaries'
+
+ id = db.Column(db.Integer, primary_key=True)
+ period_start = db.Column(db.DateTime, nullable=False, index=True)
+ api_key_id = db.Column(db.Integer, db.ForeignKey('api_keys.id'), nullable=True)
+ user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=True)
+ endpoint = db.Column(db.String(500), nullable=True)
+ total_requests = db.Column(db.Integer, default=0)
+ success_count = db.Column(db.Integer, default=0)
+ client_error_count = db.Column(db.Integer, default=0)
+ server_error_count = db.Column(db.Integer, default=0)
+ avg_response_time_ms = db.Column(db.Float, nullable=True)
+ max_response_time_ms = db.Column(db.Float, nullable=True)
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'period_start': self.period_start.isoformat() if self.period_start else None,
+ 'api_key_id': self.api_key_id,
+ 'user_id': self.user_id,
+ 'endpoint': self.endpoint,
+ 'total_requests': self.total_requests,
+ 'success_count': self.success_count,
+ 'client_error_count': self.client_error_count,
+ 'server_error_count': self.server_error_count,
+ 'avg_response_time_ms': self.avg_response_time_ms,
+ 'max_response_time_ms': self.max_response_time_ms,
+ }
diff --git a/backend/app/models/audit_log.py b/backend/app/models/audit_log.py
index b5b65757..59e77268 100644
--- a/backend/app/models/audit_log.py
+++ b/backend/app/models/audit_log.py
@@ -44,6 +44,9 @@ class AuditLog(db.Model):
ACTION_SSO_PROVISION = 'sso.provision'
ACTION_SSO_LINK = 'sso.link'
ACTION_SSO_UNLINK = 'sso.unlink'
+ ACTION_API_KEY_CREATE = 'api_key.create'
+ ACTION_API_KEY_REVOKE = 'api_key.revoke'
+ ACTION_API_KEY_ROTATE = 'api_key.rotate'
def get_details(self):
"""Return parsed details JSON."""
diff --git a/backend/app/models/event_subscription.py b/backend/app/models/event_subscription.py
new file mode 100644
index 00000000..9d4b98da
--- /dev/null
+++ b/backend/app/models/event_subscription.py
@@ -0,0 +1,144 @@
+"""Event subscription and delivery models for webhook system."""
+from datetime import datetime
+from app import db
+import json
+import secrets
+
+
+class EventSubscription(db.Model):
+ """Webhook subscription for event notifications."""
+ __tablename__ = 'event_subscriptions'
+
+ id = db.Column(db.Integer, primary_key=True)
+ user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False)
+ name = db.Column(db.String(100), nullable=False)
+ url = db.Column(db.String(2048), nullable=False)
+ secret = db.Column(db.String(256), nullable=True)
+ events = db.Column(db.Text, nullable=False) # JSON array of event types
+ is_active = db.Column(db.Boolean, default=True)
+ headers = db.Column(db.Text, nullable=True) # JSON dict of custom headers
+ retry_count = db.Column(db.Integer, default=3)
+ timeout_seconds = db.Column(db.Integer, default=10)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ user = db.relationship('User', foreign_keys=[user_id])
+ deliveries = db.relationship('EventDelivery', back_populates='subscription',
+ lazy='dynamic', cascade='all, delete-orphan')
+
+ @staticmethod
+ def generate_secret():
+ """Generate a signing secret for HMAC."""
+ return 'whsec_' + secrets.token_hex(24)
+
+ def get_events(self):
+ """Return parsed events list."""
+ if self.events:
+ try:
+ return json.loads(self.events)
+ except (json.JSONDecodeError, TypeError):
+ return []
+ return []
+
+ def set_events(self, events_list):
+ """Set events from a list."""
+ self.events = json.dumps(events_list) if events_list else '[]'
+
+ def get_headers(self):
+ """Return parsed custom headers."""
+ if self.headers:
+ try:
+ return json.loads(self.headers)
+ except (json.JSONDecodeError, TypeError):
+ return {}
+ return {}
+
+ def set_headers(self, headers_dict):
+ """Set custom headers from a dict."""
+ self.headers = json.dumps(headers_dict) if headers_dict else None
+
+ def matches_event(self, event_type):
+ """Check if this subscription matches the given event type."""
+ events = self.get_events()
+ if '*' in events:
+ return True
+ if event_type in events:
+ return True
+ # Check wildcard category match (e.g. 'app.*' matches 'app.created')
+ category = event_type.split('.')[0] if '.' in event_type else event_type
+ if f'{category}.*' in events:
+ return True
+ return False
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'user_id': self.user_id,
+ 'name': self.name,
+ 'url': self.url,
+ 'has_secret': bool(self.secret),
+ 'events': self.get_events(),
+ 'is_active': self.is_active,
+ 'headers': self.get_headers(),
+ 'retry_count': self.retry_count,
+ 'timeout_seconds': self.timeout_seconds,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+
+ def __repr__(self):
+ return f'<EventSubscription {self.name} → {self.url}>'
+
+
+class EventDelivery(db.Model):
+ """Record of a webhook delivery attempt."""
+ __tablename__ = 'event_deliveries'
+
+ id = db.Column(db.Integer, primary_key=True)
+ subscription_id = db.Column(db.Integer, db.ForeignKey('event_subscriptions.id'), nullable=False)
+ event_type = db.Column(db.String(100), nullable=False)
+ payload = db.Column(db.Text, nullable=True) # JSON
+ status = db.Column(db.String(20), default='pending') # pending | success | failed
+ http_status = db.Column(db.Integer, nullable=True)
+ response_body = db.Column(db.String(1000), nullable=True)
+ attempts = db.Column(db.Integer, default=0)
+ next_retry_at = db.Column(db.DateTime, nullable=True)
+ delivered_at = db.Column(db.DateTime, nullable=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
+ duration_ms = db.Column(db.Float, nullable=True)
+
+ subscription = db.relationship('EventSubscription', back_populates='deliveries')
+
+ STATUS_PENDING = 'pending'
+ STATUS_SUCCESS = 'success'
+ STATUS_FAILED = 'failed'
+
+ def get_payload(self):
+ if self.payload:
+ try:
+ return json.loads(self.payload)
+ except (json.JSONDecodeError, TypeError):
+ return {}
+ return {}
+
+ def set_payload(self, payload_dict):
+ self.payload = json.dumps(payload_dict) if payload_dict else None
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'subscription_id': self.subscription_id,
+ 'event_type': self.event_type,
+ 'payload': self.get_payload(),
+ 'status': self.status,
+ 'http_status': self.http_status,
+ 'response_body': self.response_body,
+ 'attempts': self.attempts,
+ 'next_retry_at': self.next_retry_at.isoformat() if self.next_retry_at else None,
+ 'delivered_at': self.delivered_at.isoformat() if self.delivered_at else None,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'duration_ms': self.duration_ms,
+ }
+
+ def __repr__(self):
+ return f'<EventDelivery {self.event_type} → {self.status}>'
diff --git a/backend/app/services/api_analytics_service.py b/backend/app/services/api_analytics_service.py
new file mode 100644
index 00000000..a7daec56
--- /dev/null
+++ b/backend/app/services/api_analytics_service.py
@@ -0,0 +1,250 @@
+"""Service for API usage analytics."""
+from datetime import datetime, timedelta
+from sqlalchemy import func, case
+from app import db
+from app.models.api_usage import ApiUsageLog, ApiUsageSummary
+
+
+class ApiAnalyticsService:
+ """Query and aggregate API usage data."""
+
+ @staticmethod
+ def get_overview(period='24h'):
+ """Get overall API usage stats for a period."""
+ since = _period_to_datetime(period)
+ query = ApiUsageLog.query.filter(ApiUsageLog.created_at >= since)
+
+ total = query.count()
+ if total == 0:
+ return {
+ 'total_requests': 0,
+ 'error_rate': 0,
+ 'avg_response_time_ms': 0,
+ 'success_count': 0,
+ 'client_error_count': 0,
+ 'server_error_count': 0,
+ }
+
+ stats = db.session.query(
+ func.count(ApiUsageLog.id).label('total'),
+ func.avg(ApiUsageLog.response_time_ms).label('avg_time'),
+ func.sum(case((ApiUsageLog.status_code < 400, 1), else_=0)).label('success'),
+ func.sum(case((ApiUsageLog.status_code.between(400, 499), 1), else_=0)).label('client_errors'),
+ func.sum(case((ApiUsageLog.status_code >= 500, 1), else_=0)).label('server_errors'),
+ ).filter(ApiUsageLog.created_at >= since).first()
+
+ total_req = stats.total or 0
+ error_count = (stats.client_errors or 0) + (stats.server_errors or 0)
+
+ return {
+ 'total_requests': total_req,
+ 'error_rate': round(error_count / total_req * 100, 2) if total_req > 0 else 0,
+ 'avg_response_time_ms': round(stats.avg_time or 0, 2),
+ 'success_count': stats.success or 0,
+ 'client_error_count': stats.client_errors or 0,
+ 'server_error_count': stats.server_errors or 0,
+ }
+
+ @staticmethod
+ def get_endpoint_stats(period='24h', limit=20):
+ """Get top endpoints by request count."""
+ since = _period_to_datetime(period)
+
+ results = db.session.query(
+ ApiUsageLog.endpoint,
+ ApiUsageLog.method,
+ func.count(ApiUsageLog.id).label('count'),
+ func.avg(ApiUsageLog.response_time_ms).label('avg_time'),
+ func.sum(case((ApiUsageLog.status_code >= 400, 1), else_=0)).label('errors'),
+ ).filter(
+ ApiUsageLog.created_at >= since
+ ).group_by(
+ ApiUsageLog.endpoint, ApiUsageLog.method
+ ).order_by(
+ func.count(ApiUsageLog.id).desc()
+ ).limit(limit).all()
+
+ return [{
+ 'endpoint': r.endpoint,
+ 'method': r.method,
+ 'count': r.count,
+ 'avg_response_time_ms': round(r.avg_time or 0, 2),
+ 'error_count': r.errors or 0,
+ } for r in results]
+
+ @staticmethod
+ def get_error_stats(period='24h'):
+ """Get error breakdown by status code."""
+ since = _period_to_datetime(period)
+
+ results = db.session.query(
+ ApiUsageLog.status_code,
+ ApiUsageLog.endpoint,
+ func.count(ApiUsageLog.id).label('count'),
+ ).filter(
+ ApiUsageLog.created_at >= since,
+ ApiUsageLog.status_code >= 400,
+ ).group_by(
+ ApiUsageLog.status_code, ApiUsageLog.endpoint
+ ).order_by(
+ func.count(ApiUsageLog.id).desc()
+ ).limit(50).all()
+
+ return [{
+ 'status_code': r.status_code,
+ 'endpoint': r.endpoint,
+ 'count': r.count,
+ } for r in results]
+
+ @staticmethod
+ def get_time_series(period='24h', interval='hour'):
+ """Get request counts over time for charting."""
+ since = _period_to_datetime(period)
+
+ # Use raw logs grouped by truncated time
+ if interval == 'hour':
+ trunc = func.strftime('%Y-%m-%d %H:00:00', ApiUsageLog.created_at)
+ elif interval == 'day':
+ trunc = func.strftime('%Y-%m-%d', ApiUsageLog.created_at)
+ else:
+ trunc = func.strftime('%Y-%m-%d %H:%M:00', ApiUsageLog.created_at)
+
+ results = db.session.query(
+ trunc.label('period'),
+ func.count(ApiUsageLog.id).label('count'),
+ func.sum(case((ApiUsageLog.status_code >= 400, 1), else_=0)).label('errors'),
+ func.avg(ApiUsageLog.response_time_ms).label('avg_time'),
+ ).filter(
+ ApiUsageLog.created_at >= since
+ ).group_by('period').order_by('period').all()
+
+ return [{
+ 'period': r.period,
+ 'count': r.count,
+ 'errors': r.errors or 0,
+ 'avg_response_time_ms': round(r.avg_time or 0, 2),
+ } for r in results]
+
+ @staticmethod
+ def get_key_usage(api_key_id, period='24h'):
+ """Get usage stats for a specific API key."""
+ since = _period_to_datetime(period)
+
+ stats = db.session.query(
+ func.count(ApiUsageLog.id).label('total'),
+ func.avg(ApiUsageLog.response_time_ms).label('avg_time'),
+ func.sum(case((ApiUsageLog.status_code >= 400, 1), else_=0)).label('errors'),
+ ).filter(
+ ApiUsageLog.api_key_id == api_key_id,
+ ApiUsageLog.created_at >= since,
+ ).first()
+
+ # Top endpoints for this key
+ endpoints = db.session.query(
+ ApiUsageLog.endpoint,
+ func.count(ApiUsageLog.id).label('count'),
+ ).filter(
+ ApiUsageLog.api_key_id == api_key_id,
+ ApiUsageLog.created_at >= since,
+ ).group_by(
+ ApiUsageLog.endpoint
+ ).order_by(
+ func.count(ApiUsageLog.id).desc()
+ ).limit(10).all()
+
+ return {
+ 'total_requests': stats.total or 0,
+ 'avg_response_time_ms': round(stats.avg_time or 0, 2),
+ 'error_count': stats.errors or 0,
+ 'top_endpoints': [{'endpoint': e.endpoint, 'count': e.count} for e in endpoints],
+ }
+
+ @staticmethod
+ def aggregate_hourly():
+ """Roll up raw logs into hourly summaries."""
+ # Find the latest summary period
+ latest = db.session.query(
+ func.max(ApiUsageSummary.period_start)
+ ).scalar()
+
+ if latest:
+ since = latest
+ else:
+ since = datetime.utcnow() - timedelta(days=7)
+
+ # Group raw logs by hour, endpoint, user, api_key
+ trunc = func.strftime('%Y-%m-%d %H:00:00', ApiUsageLog.created_at)
+
+ results = db.session.query(
+ trunc.label('period'),
+ ApiUsageLog.api_key_id,
+ ApiUsageLog.user_id,
+ ApiUsageLog.endpoint,
+ func.count(ApiUsageLog.id).label('total'),
+ func.sum(case((ApiUsageLog.status_code < 400, 1), else_=0)).label('success'),
+ func.sum(case((ApiUsageLog.status_code.between(400, 499), 1), else_=0)).label('client_errors'),
+ func.sum(case((ApiUsageLog.status_code >= 500, 1), else_=0)).label('server_errors'),
+ func.avg(ApiUsageLog.response_time_ms).label('avg_time'),
+ func.max(ApiUsageLog.response_time_ms).label('max_time'),
+ ).filter(
+ ApiUsageLog.created_at >= since
+ ).group_by(
+ 'period', ApiUsageLog.api_key_id, ApiUsageLog.user_id, ApiUsageLog.endpoint
+ ).all()
+
+ for r in results:
+ try:
+ period_start = datetime.strptime(r.period, '%Y-%m-%d %H:%M:%S')
+ except (ValueError, TypeError):
+ continue
+
+ # Check if summary already exists
+ existing = ApiUsageSummary.query.filter_by(
+ period_start=period_start,
+ api_key_id=r.api_key_id,
+ user_id=r.user_id,
+ endpoint=r.endpoint,
+ ).first()
+
+ if existing:
+ continue
+
+ summary = ApiUsageSummary(
+ period_start=period_start,
+ api_key_id=r.api_key_id,
+ user_id=r.user_id,
+ endpoint=r.endpoint,
+ total_requests=r.total or 0,
+ success_count=r.success or 0,
+ client_error_count=r.client_errors or 0,
+ server_error_count=r.server_errors or 0,
+ avg_response_time_ms=round(r.avg_time or 0, 2),
+ max_response_time_ms=round(r.max_time or 0, 2),
+ )
+ db.session.add(summary)
+
+ db.session.commit()
+
+ @staticmethod
+ def cleanup_old_logs(days=30):
+ """Purge raw usage logs older than specified days."""
+ cutoff = datetime.utcnow() - timedelta(days=days)
+ deleted = ApiUsageLog.query.filter(ApiUsageLog.created_at < cutoff).delete()
+ db.session.commit()
+ return deleted
+
+
+def _period_to_datetime(period):
+ """Convert a period string to a datetime."""
+ now = datetime.utcnow()
+ if period == '1h':
+ return now - timedelta(hours=1)
+ elif period == '24h':
+ return now - timedelta(hours=24)
+ elif period == '7d':
+ return now - timedelta(days=7)
+ elif period == '30d':
+ return now - timedelta(days=30)
+ elif period == '90d':
+ return now - timedelta(days=90)
+ return now - timedelta(hours=24)
diff --git a/backend/app/services/api_key_service.py b/backend/app/services/api_key_service.py
new file mode 100644
index 00000000..29a0068a
--- /dev/null
+++ b/backend/app/services/api_key_service.py
@@ -0,0 +1,126 @@
+"""Service for API key management."""
+from datetime import datetime
+from app import db
+from app.models.api_key import ApiKey
+
+
+class ApiKeyService:
+ """CRUD and validation for API keys."""
+
+ @staticmethod
+ def create_key(user_id, name, scopes=None, tier='standard', expires_at=None):
+ """Create a new API key. Returns (api_key_record, raw_key)."""
+ if tier not in ApiKey.VALID_TIERS:
+ tier = ApiKey.TIER_STANDARD
+
+ raw_key, prefix, key_hash = ApiKey.generate_key()
+
+ api_key = ApiKey(
+ user_id=user_id,
+ name=name,
+ key_prefix=prefix,
+ key_hash=key_hash,
+ tier=tier,
+ expires_at=expires_at,
+ )
+ api_key.set_scopes(scopes)
+
+ db.session.add(api_key)
+ db.session.commit()
+
+ return api_key, raw_key
+
+ @staticmethod
+ def validate_key(raw_key):
+ """Validate a raw API key. Returns ApiKey if valid, None otherwise."""
+ if not raw_key or not raw_key.startswith('sk_'):
+ return None
+
+ key_hash = ApiKey.hash_key(raw_key)
+ api_key = ApiKey.query.filter_by(key_hash=key_hash).first()
+
+ if not api_key:
+ return None
+ if not api_key.is_valid():
+ return None
+
+ return api_key
+
+ @staticmethod
+ def revoke_key(key_id, user_id):
+ """Revoke an API key."""
+ api_key = ApiKey.query.filter_by(id=key_id, user_id=user_id).first()
+ if not api_key:
+ return None
+
+ api_key.is_active = False
+ api_key.revoked_at = datetime.utcnow()
+ db.session.commit()
+ return api_key
+
+ @staticmethod
+ def list_keys(user_id):
+ """List all API keys for a user."""
+ return ApiKey.query.filter_by(user_id=user_id).order_by(
+ ApiKey.created_at.desc()
+ ).all()
+
+ @staticmethod
+ def get_key(key_id, user_id=None):
+ """Get a single API key by ID."""
+ query = ApiKey.query.filter_by(id=key_id)
+ if user_id:
+ query = query.filter_by(user_id=user_id)
+ return query.first()
+
+ @staticmethod
+ def update_key(key_id, user_id, name=None, scopes=None, tier=None):
+ """Update an API key's metadata."""
+ api_key = ApiKey.query.filter_by(id=key_id, user_id=user_id).first()
+ if not api_key:
+ return None
+
+ if name is not None:
+ api_key.name = name
+ if scopes is not None:
+ api_key.set_scopes(scopes)
+ if tier is not None and tier in ApiKey.VALID_TIERS:
+ api_key.tier = tier
+
+ db.session.commit()
+ return api_key
+
+ @staticmethod
+ def rotate_key(key_id, user_id):
+ """Rotate an API key: revoke old, create new with same config."""
+ old_key = ApiKey.query.filter_by(id=key_id, user_id=user_id).first()
+ if not old_key:
+ return None, None
+
+ # Capture config before revoking
+ name = old_key.name
+ scopes = old_key.get_scopes()
+ tier = old_key.tier
+ expires_at = old_key.expires_at
+
+ # Revoke old key
+ old_key.is_active = False
+ old_key.revoked_at = datetime.utcnow()
+
+ # Create new key with same config
+ new_key, raw_key = ApiKeyService.create_key(
+ user_id=user_id,
+ name=name,
+ scopes=scopes,
+ tier=tier,
+ expires_at=expires_at,
+ )
+
+ return new_key, raw_key
+
+ @staticmethod
+ def check_scope(api_key, required_scope):
+ """Check if an API key has the required scope."""
+ if not api_key:
+ return False
+ return api_key.has_scope(required_scope)
diff --git a/backend/app/services/audit_service.py b/backend/app/services/audit_service.py
index e0ee93d6..8f445705 100644
--- a/backend/app/services/audit_service.py
+++ b/backend/app/services/audit_service.py
@@ -46,6 +46,14 @@ class AuditService:
ip_address=ip_address,
user_agent=user_agent
)
+
+ # Emit webhook event for matching audit actions
+ try:
+ from app.services.event_service import EventService
+ EventService.emit_for_audit(action, target_type, target_id, details, user_id)
+ except Exception:
+ pass # Don't let event emission failures break audit logging
+
return log_entry
@staticmethod
diff --git a/backend/app/services/event_service.py b/backend/app/services/event_service.py
new file mode 100644
index 00000000..ed392939
--- /dev/null
+++ b/backend/app/services/event_service.py
@@ -0,0 +1,268 @@
+"""Service for event emission and webhook delivery."""
+import hashlib
+import hmac
+import json
+import logging
+import time
+import threading
+import uuid
+from datetime import datetime, timedelta
+
+import requests as http_requests
+
+from app import db
+from app.models.event_subscription import EventSubscription, EventDelivery
+
+logger = logging.getLogger(__name__)
+
+# Mapping from audit log actions to event types
+AUDIT_TO_EVENT = {
+ 'app.create': 'app.created',
+ 'app.update': 'app.updated',
+ 'app.delete': 'app.deleted',
+ 'app.start': 'app.started',
+ 'app.stop': 'app.stopped',
+ 'app.restart': 'app.restarted',
+ 'app.deploy': 'app.deployed',
+ 'backup.create': 'backup.created',
+ 'backup.restore': 'backup.restored',
+ 'user.create': 'user.created',
+ 'user.login': 'user.login',
+ 'api_key.create': 'api_key.created',
+ 'api_key.revoke': 'api_key.revoked',
+}
+
+# Available events catalog
+EVENT_CATALOG = [
+ {'type': 'app.created', 'category': 'Applications', 'description': 'An application was created'},
+ {'type': 'app.updated', 'category': 'Applications', 'description': 'An application was updated'},
+ {'type': 'app.deleted', 'category': 'Applications', 'description': 'An application was deleted'},
+ {'type': 'app.started', 'category': 'Applications', 'description': 'An application was started'},
+ {'type': 'app.stopped', 'category': 'Applications', 'description': 'An application was stopped'},
+ {'type': 'app.restarted', 'category': 'Applications', 'description': 'An application was restarted'},
+ {'type': 'app.deployed', 'category': 'Applications', 'description': 'An application was deployed'},
+ {'type': 'container.started', 'category': 'Docker', 'description': 'A container was started'},
+ {'type': 'container.stopped', 'category': 'Docker', 'description': 'A container was stopped'},
+ {'type': 'backup.created', 'category': 'Backups', 'description': 'A backup was created'},
+ {'type': 'backup.restored', 'category': 'Backups', 'description': 'A backup was restored'},
+ {'type': 'user.created', 'category': 'Users', 'description': 'A user was created'},
+ {'type': 'user.login', 'category': 'Users', 'description': 'A user logged in'},
+ {'type': 'security.alert', 'category': 'Security', 'description': 'A security alert was triggered'},
+ {'type': 'ssl.expiring', 'category': 'SSL', 'description': 'An SSL certificate is expiring soon'},
+ {'type': 'domain.created', 'category': 'Domains', 'description': 'A domain was created'},
+ {'type': 'domain.deleted', 'category': 'Domains', 'description': 'A domain was deleted'},
+ {'type': 'api_key.created', 'category': 'API', 'description': 'An API key was created'},
+ {'type': 'api_key.revoked', 'category': 'API', 'description': 'An API key was revoked'},
+]
+
+
+class EventService:
+ """Service for emitting events and delivering webhooks."""
+
+ @staticmethod
+ def get_available_events():
+ """Return the event catalog."""
+ return EVENT_CATALOG
+
+ @staticmethod
+ def emit(event_type, payload, user_id=None):
+ """Emit an event to all matching subscriptions."""
+ subscriptions = EventSubscription.query.filter_by(is_active=True).all()
+ matching = [s for s in subscriptions if s.matches_event(event_type)]
+
+ if not matching:
+ return
+
+ for sub in matching:
+ delivery = EventDelivery(
+ subscription_id=sub.id,
+ event_type=event_type,
+ status=EventDelivery.STATUS_PENDING,
+ )
+ delivery.set_payload(payload)
+ db.session.add(delivery)
+
+ db.session.commit()
+
+ # Dispatch deliveries in background
+ for sub in matching:
+ pending = EventDelivery.query.filter_by(
+ subscription_id=sub.id,
+ event_type=event_type,
+ status=EventDelivery.STATUS_PENDING,
+ ).order_by(EventDelivery.created_at.desc()).first()
+
+ if pending:
+ thread = threading.Thread(
+ target=EventService._deliver_in_thread,
+ args=(pending.id,),
+ daemon=True,
+ )
+ thread.start()
+
+ @staticmethod
+ def emit_for_audit(action, target_type, target_id, details, user_id):
+ """Emit an event based on an audit log action."""
+ event_type = AUDIT_TO_EVENT.get(action)
+ if not event_type:
+ return
+
+ payload = {
+ 'event': event_type,
+ 'timestamp': datetime.utcnow().isoformat(),
+ 'target_type': target_type,
+ 'target_id': target_id,
+ 'user_id': user_id,
+ 'details': details or {},
+ }
+
+ try:
+ EventService.emit(event_type, payload, user_id)
+ except Exception as e:
+ logger.error(f'Failed to emit event {event_type}: {e}')
+
+ @staticmethod
+ def _deliver_in_thread(delivery_id):
+ """Deliver a webhook in a background thread."""
+ from flask import current_app
+ try:
+ app = current_app._get_current_object()
+ except RuntimeError:
+ # No app context - need to import create_app
+ return
+
+ with app.app_context():
+ EventService.deliver(delivery_id)
+
+ @staticmethod
+ def deliver(delivery_id):
+ """Deliver a webhook to the subscription URL."""
+ delivery = EventDelivery.query.get(delivery_id)
+ if not delivery:
+ return
+
+ subscription = delivery.subscription
+ if not subscription or not subscription.is_active:
+ delivery.status = EventDelivery.STATUS_FAILED
+ db.session.commit()
+ return
+
+ payload = delivery.get_payload()
+ payload_json = json.dumps(payload)
+ delivery_uuid = str(uuid.uuid4())
+
+ headers = {
+ 'Content-Type': 'application/json',
+ 'X-ServerKit-Event': delivery.event_type,
+ 'X-ServerKit-Delivery': delivery_uuid,
+ 'User-Agent': 'ServerKit-Webhooks/1.0',
+ }
+
+ # HMAC signature if secret is set
+ if subscription.secret:
+ signature = hmac.new(
+ subscription.secret.encode(),
+ payload_json.encode(),
+ hashlib.sha256,
+ ).hexdigest()
+ headers['X-ServerKit-Signature'] = f'sha256={signature}'
+
+ # Add custom headers
+ custom_headers = subscription.get_headers()
+ if custom_headers:
+ headers.update(custom_headers)
+
+ delivery.attempts = (delivery.attempts or 0) + 1
+ start_time = time.time()
+
+ try:
+ resp = http_requests.post(
+ subscription.url,
+ data=payload_json,
+ headers=headers,
+ timeout=subscription.timeout_seconds or 10,
+ )
+ elapsed_ms = (time.time() - start_time) * 1000
+
+ delivery.http_status = resp.status_code
+ delivery.response_body = resp.text[:1000] if resp.text else None
+ delivery.duration_ms = round(elapsed_ms, 2)
+
+ if 200 <= resp.status_code < 300:
+ delivery.status = EventDelivery.STATUS_SUCCESS
+ delivery.delivered_at = datetime.utcnow()
+ else:
+ _schedule_retry(delivery, subscription)
+
+ except Exception as e:
+ elapsed_ms = (time.time() - start_time) * 1000
+ delivery.duration_ms = round(elapsed_ms, 2)
+ delivery.response_body = str(e)[:1000]
+ _schedule_retry(delivery, subscription)
+
+ db.session.commit()
+
+ @staticmethod
+ def retry_failed():
+ """Retry failed deliveries that are due."""
+ now = datetime.utcnow()
+ pending = EventDelivery.query.filter(
+ EventDelivery.status == EventDelivery.STATUS_PENDING,
+ EventDelivery.next_retry_at <= now,
+ EventDelivery.attempts > 0,
+ ).all()
+
+ for delivery in pending:
+ EventService.deliver(delivery.id)
+
+ @staticmethod
+ def send_test(subscription_id):
+ """Send a test event to a subscription."""
+ sub = EventSubscription.query.get(subscription_id)
+ if not sub:
+ return None
+
+ delivery = EventDelivery(
+ subscription_id=sub.id,
+ event_type='test.ping',
+ status=EventDelivery.STATUS_PENDING,
+ )
+ delivery.set_payload({
+ 'event': 'test.ping',
+ 'timestamp': datetime.utcnow().isoformat(),
+ 'message': 'This is a test webhook from ServerKit',
+ })
+ db.session.add(delivery)
+ db.session.commit()
+
+ EventService.deliver(delivery.id)
+ return delivery
+
+ @staticmethod
+ def get_deliveries(subscription_id, page=1, per_page=50):
+ """Get delivery history for a subscription."""
+ return EventDelivery.query.filter_by(
+ subscription_id=subscription_id
+ ).order_by(
+ EventDelivery.created_at.desc()
+ ).paginate(page=page, per_page=per_page, error_out=False)
+
+ @staticmethod
+ def cleanup_old_deliveries(days=30):
+ """Purge old delivery records."""
+ cutoff = datetime.utcnow() - timedelta(days=days)
+ deleted = EventDelivery.query.filter(EventDelivery.created_at < cutoff).delete()
+ db.session.commit()
+ return deleted
+
+
+def _schedule_retry(delivery, subscription):
+ """Schedule a retry with exponential backoff."""
+ max_retries = subscription.retry_count or 3
+ if delivery.attempts >= max_retries:
+ delivery.status = EventDelivery.STATUS_FAILED
+ else:
+ # Exponential backoff: 10s, 30s, 90s
+ delay_seconds = 10 * (3 ** (delivery.attempts - 1))
+ delivery.next_retry_at = datetime.utcnow() + timedelta(seconds=delay_seconds)
+ delivery.status = EventDelivery.STATUS_PENDING
diff --git a/backend/app/services/openapi_service.py b/backend/app/services/openapi_service.py
new file mode 100644
index 00000000..a4362a12
--- /dev/null
+++ b/backend/app/services/openapi_service.py
@@ -0,0 +1,230 @@
+"""Service for generating OpenAPI 3.0 specification."""
+import re
+from flask import current_app
+
+
+class OpenAPIService:
+ """Auto-generates OpenAPI 3.0 spec from registered Flask routes."""
+
+ # Blueprint name to tag mapping
+ TAG_MAP = {
+ 'auth': 'Authentication',
+ 'apps': 'Applications',
+ 'domains': 'Domains',
+ 'docker': 'Docker',
+ 'databases': 'Databases',
+ 'system': 'System',
+ 'processes': 'Processes',
+ 'logs': 'Logs',
+ 'nginx': 'Nginx',
+ 'ssl': 'SSL Certificates',
+ 'php': 'PHP',
+ 'wordpress': 'WordPress',
+ 'wordpress_sites': 'WordPress Sites',
+ 'python': 'Python',
+ 'monitoring': 'Monitoring',
+ 'notifications': 'Notifications',
+ 'backups': 'Backups',
+ 'deploy': 'Deployment',
+ 'builds': 'Builds',
+ 'templates': 'Templates',
+ 'files': 'File Manager',
+ 'ftp': 'FTP Server',
+ 'firewall': 'Firewall',
+ 'git': 'Git Server',
+ 'security': 'Security',
+ 'cron': 'Cron Jobs',
+ 'email': 'Email',
+ 'uptime': 'Uptime',
+ 'admin': 'Admin',
+ 'metrics': 'Metrics',
+ 'workflows': 'Workflows',
+ 'servers': 'Servers',
+ 'api_keys': 'API Keys',
+ 'api_analytics': 'API Analytics',
+ 'event_subscriptions': 'Event Subscriptions',
+ 'two_factor': 'Two-Factor Auth',
+ 'sso': 'SSO / OAuth',
+ 'migrations': 'Database Migrations',
+ 'env_vars': 'Environment Variables',
+ 'private_urls': 'Private URLs',
+ }
+
+ @staticmethod
+ def generate_spec():
+ """Generate the full OpenAPI 3.0 spec."""
+ app = current_app
+
+ spec = {
+ 'openapi': '3.0.3',
+ 'info': {
+ 'title': 'ServerKit API',
+ 'description': 'Server control panel API for managing web applications, databases, Docker containers, and security.',
+ 'version': '1.0.0',
+ 'contact': {
+ 'name': 'ServerKit',
+ },
+ },
+ 'servers': [
+ {
+ 'url': '/api/v1',
+ 'description': 'API v1',
+ },
+ ],
+ 'components': {
+ 'securitySchemes': {
+ 'BearerAuth': {
+ 'type': 'http',
+ 'scheme': 'bearer',
+ 'bearerFormat': 'JWT',
+ 'description': 'JWT access token',
+ },
+ 'ApiKeyAuth': {
+ 'type': 'apiKey',
+ 'in': 'header',
+ 'name': 'X-API-Key',
+ 'description': 'API key (sk_...)',
+ },
+ },
+ 'schemas': {
+ 'Error': {
+ 'type': 'object',
+ 'properties': {
+ 'error': {
+ 'type': 'string',
+ 'description': 'Error message',
+ },
+ },
+ },
+ 'Message': {
+ 'type': 'object',
+ 'properties': {
+ 'message': {
+ 'type': 'string',
+ 'description': 'Success message',
+ },
+ },
+ },
+ },
+ 'responses': {
+ '401': {
+ 'description': 'Unauthorized',
+ 'content': {
+ 'application/json': {
+ 'schema': {'$ref': '#/components/schemas/Error'},
+ },
+ },
+ },
+ '403': {
+ 'description': 'Forbidden',
+ 'content': {
+ 'application/json': {
+ 'schema': {'$ref': '#/components/schemas/Error'},
+ },
+ },
+ },
+ '404': {
+ 'description': 'Not found',
+ 'content': {
+ 'application/json': {
+ 'schema': {'$ref': '#/components/schemas/Error'},
+ },
+ },
+ },
+ },
+ },
+ 'security': [
+ {'BearerAuth': []},
+ {'ApiKeyAuth': []},
+ ],
+ 'paths': {},
+ 'tags': [],
+ }
+
+ # Collect tags and paths from registered routes
+ tags_seen = set()
+ paths = {}
+
+ for rule in app.url_map.iter_rules():
+ # Only include API routes
+ if not rule.rule.startswith('/api/v1/'):
+ continue
+
+ # Skip static and internal routes
+ if rule.endpoint == 'static' or rule.rule.endswith('/openapi.json'):
+ continue
+
+ # Get blueprint name
+ parts = rule.endpoint.split('.')
+ bp_name = parts[0] if len(parts) > 1 else None
+
+ # Convert Flask URL params to OpenAPI format
+ path = rule.rule.replace('/api/v1', '')
+ path = re.sub(r'<(?:int:|string:|float:)?(\w+)>', r'{\1}', path)
+
+ # Get tag
+ tag = OpenAPIService.TAG_MAP.get(bp_name, bp_name or 'Other')
+ if tag not in tags_seen:
+ tags_seen.add(tag)
+
+ # Get view function docstring
+ view_func = app.view_functions.get(rule.endpoint)
+ description = ''
+ if view_func and view_func.__doc__:
+ description = view_func.__doc__.strip()
+
+ # Build path item
+ if path not in paths:
+ paths[path] = {}
+
+ methods = [m.lower() for m in rule.methods if m not in ('HEAD', 'OPTIONS')]
+ for method in methods:
+ operation = {
+ 'tags': [tag],
+ 'summary': description or f'{method.upper()} {path}',
+ 'operationId': rule.endpoint.replace('.', '_'),
+ 'responses': {
+ '200': {
+ 'description': 'Success',
+ 'content': {
+ 'application/json': {
+ 'schema': {'type': 'object'},
+ },
+ },
+ },
+ '401': {'$ref': '#/components/responses/401'},
+ '403': {'$ref': '#/components/responses/403'},
+ },
+ }
+
+ # Add path parameters
+ params = re.findall(r'\{(\w+)\}', path)
+ if params:
+ operation['parameters'] = []
+ for param in params:
+ operation['parameters'].append({
+ 'name': param,
+ 'in': 'path',
+ 'required': True,
+ 'schema': {'type': 'integer' if param.endswith('_id') or param == 'id' else 'string'},
+ })
+
+ # Add request body for POST/PUT/PATCH
+ if method in ('post', 'put', 'patch'):
+ operation['requestBody'] = {
+ 'content': {
+ 'application/json': {
+ 'schema': {'type': 'object'},
+ },
+ },
+ }
+
+ if len(methods) > 1:
+ operation['operationId'] = f'{rule.endpoint.replace(".", "_")}_{method}'
+
+ paths[path][method] = operation
+
+ spec['paths'] = dict(sorted(paths.items()))
+ spec['tags'] = [{'name': t} for t in sorted(tags_seen)]
+
+ return spec
diff --git a/backend/app/services/settings_service.py b/backend/app/services/settings_service.py
index 69db1d70..404edf26 100644
--- a/backend/app/services/settings_service.py
+++ b/backend/app/services/settings_service.py
@@ -59,6 +59,11 @@ class SettingsService:
'sso_default_role': {'value': 'developer', 'type': 'string', 'description': 'Default role for SSO-provisioned users'},
'sso_force_sso': {'value': False, 'type': 'boolean', 'description': 'Disable password login (SSO only)'},
'sso_allowed_domains': {'value': [], 'type': 'json', 'description': 'Restrict SSO to these email domains'},
+ # Rate limiting settings
+ 'rate_limit_standard': {'value': '100 per minute', 'type': 'string', 'description': 'Rate limit for standard API keys'},
+ 'rate_limit_elevated': {'value': '500 per minute', 'type': 'string', 'description': 'Rate limit for elevated API keys'},
+ 'rate_limit_unlimited': {'value': '5000 per minute', 'type': 'string', 'description': 'Rate limit for unlimited API keys'},
+ 'rate_limit_unauthenticated': {'value': '30 per minute', 'type': 'string', 'description': 'Rate limit for unauthenticated requests'},
}
@staticmethod
diff --git a/backend/requirements.txt b/backend/requirements.txt
index fddada77..165a7811 100644
--- a/backend/requirements.txt
+++ b/backend/requirements.txt
@@ -58,4 +58,8 @@ boto3==1.35.0
# SSO / OAuth
Authlib==1.5.2
-python3-saml==1.16.0
\ No newline at end of file
+python3-saml==1.16.0
+
+# OpenAPI documentation
+apispec==6.4.0
+apispec-webframeworks==1.2.0
\ No newline at end of file
diff --git a/frontend/src/components/settings/ApiKeyModal.jsx b/frontend/src/components/settings/ApiKeyModal.jsx
new file mode 100644
index 00000000..d255f30f
--- /dev/null
+++ b/frontend/src/components/settings/ApiKeyModal.jsx
@@ -0,0 +1,179 @@
+import { useState } from 'react';
+import { X, Copy, Check, AlertTriangle } from 'lucide-react';
+
+const SCOPE_OPTIONS = [
+ { value: '*', label: 'Full Access' },
+ { value: 'apps:read', label: 'Apps (Read)' },
+ { value: 'apps:write', label: 'Apps (Write)' },
+ { value: 'docker:read', label: 'Docker (Read)' },
+ { value: 'docker:write', label: 'Docker (Write)' },
+ { value: 'system:read', label: 'System (Read)' },
+ { value: 'databases:read', label: 'Databases (Read)' },
+ { value: 'databases:write', label: 'Databases (Write)' },
+ { value: 'backups:read', label: 'Backups (Read)' },
+ { value: 'backups:write', label: 'Backups (Write)' },
+ { value: 'domains:read', label: 'Domains (Read)' },
+ { value: 'domains:write', label: 'Domains (Write)' },
+];
+
+const TIER_OPTIONS = [
+ { value: 'standard', label: 'Standard', desc: '100 req/min' },
+ { value: 'elevated', label: 'Elevated', desc: '500 req/min' },
+ { value: 'unlimited', label: 'Unlimited', desc: '5000 req/min' },
+];
+
+const ApiKeyModal = ({ onClose, onSubmit, createdKey }) => {
+ const [name, setName] = useState('');
+ const [scopes, setScopes] = useState(['*']);
+ const [tier, setTier] = useState('standard');
+ const [expiresAt, setExpiresAt] = useState('');
+ const [saving, setSaving] = useState(false);
+ const [copied, setCopied] = useState(false);
+
+ const handleScopeToggle = (scope) => {
+ if (scope === '*') {
+ setScopes(['*']);
+ return;
+ }
+ setScopes(prev => {
+ const filtered = prev.filter(s => s !== '*');
+ if (filtered.includes(scope)) {
+ return filtered.filter(s => s !== scope);
+ }
+ return [...filtered, scope];
+ });
+ };
+
+ const handleSubmit = async (e) => {
+ e.preventDefault();
+ if (!name.trim()) return;
+ setSaving(true);
+ try {
+ await onSubmit({
+ name: name.trim(),
+ scopes,
+ tier,
+ expires_at: expiresAt || null,
+ });
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const copyKey = () => {
+ if (createdKey) {
+ navigator.clipboard.writeText(createdKey);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ }
+ };
+
+ // Show created key view
+ if (createdKey) {
+ return (
+ <div className="modal-overlay" onClick={onClose}>
+ <div className="modal api-key-modal" onClick={e => e.stopPropagation()}>
+ <div className="modal-header">
+ <h3>API Key Created</h3>
+ <button className="modal-close" onClick={onClose}><X size={18} /></button>
+ </div>
+ <div className="modal-body">
+ <div className="api-key-modal__warning">
+ <AlertTriangle size={16} />
+ <span>Copy this key now. It will not be shown again.</span>
+ </div>
+ <div className="api-key-modal__key-display">
+ <code>{createdKey}</code>
+ <button className="btn btn-sm btn-secondary" onClick={copyKey}>
+ {copied ? <Check size={14} /> : <Copy size={14} />}
+ {copied ? 'Copied' : 'Copy'}
+ </button>
+ </div>
+ </div>
+ <div className="modal-footer">
+ <button className="btn btn-primary" onClick={onClose}>Done</button>
+ </div>
+ </div>
+ </div>
+ );
+ }
+
+ return (
+ <div className="modal-overlay" onClick={onClose}>
+ <div className="modal api-key-modal" onClick={e => e.stopPropagation()}>
+ <div className="modal-header">
+ <h3>Create API Key</h3>
+ <button className="modal-close" onClick={onClose}><X size={18} /></button>
+ </div>
+ <form onSubmit={handleSubmit}>
+ <div className="modal-body">
+ <div className="form-group">
+ <label>Name</label>
+ <input
+ type="text"
+ className="form-input"
+ value={name}
+ onChange={e => setName(e.target.value)}
+ placeholder="e.g. CI/CD Pipeline, Monitoring Script"
+ required
+ />
+ </div>
+
+ <div className="form-group">
+ <label>Tier</label>
+ <div className="api-key-modal__tiers">
+ {TIER_OPTIONS.map(t => (
+ <button
+ key={t.value}
+ type="button"
+ className={`api-key-modal__tier-btn ${tier === t.value ? 'active' : ''}`}
+ onClick={() => setTier(t.value)}
+ >
+ <span className="api-key-modal__tier-label">{t.label}</span>
+ <span className="api-key-modal__tier-desc">{t.desc}</span>
+ </button>
+ ))}
+ </div>
+ </div>
+
+ <div className="form-group">
+ <label>Scopes</label>
+ <div className="api-key-modal__scopes">
+ {SCOPE_OPTIONS.map(s => (
+ <label key={s.value} className="api-key-modal__scope-item">
+ <input
+ type="checkbox"
+ checked={scopes.includes(s.value) || (s.value !== '*' && scopes.includes('*'))}
+ disabled={s.value !== '*' && scopes.includes('*')}
+ onChange={() => handleScopeToggle(s.value)}
+ />
+ <span>{s.label}</span>
+ </label>
+ ))}
+ </div>
+ </div>
+
+ <div className="form-group">
+ <label>Expiration (optional)</label>
+ <input
+ type="datetime-local"
+ className="form-input"
+ value={expiresAt}
+ onChange={e => setExpiresAt(e.target.value)}
+ />
+ <span className="form-help">Leave empty for no expiration</span>
+ </div>
+ </div>
+ <div className="modal-footer">
+ <button type="button" className="btn btn-secondary" onClick={onClose}>Cancel</button>
+ <button type="submit" className="btn btn-primary" disabled={saving || !name.trim()}>
+ {saving ? 'Creating...' : 'Create Key'}
+ </button>
+ </div>
+ </form>
+ </div>
+ </div>
+ );
+};
+
+export default ApiKeyModal;
diff --git a/frontend/src/components/settings/ApiSettingsTab.jsx b/frontend/src/components/settings/ApiSettingsTab.jsx
new file mode 100644
index 00000000..d444c6f3
--- /dev/null
+++ b/frontend/src/components/settings/ApiSettingsTab.jsx
@@ -0,0 +1,555 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useAuth } from '../../contexts/AuthContext';
+import api from '../../services/api';
+import ApiKeyModal from './ApiKeyModal';
+import WebhookSubscriptionModal from './WebhookSubscriptionModal';
+import {
+ Key, Plus, Trash2, RotateCcw, Activity, AlertCircle,
+ Check, Send, ChevronDown, ChevronUp, Zap, BarChart3, RefreshCw
+} from 'lucide-react';
+
+const ApiSettingsTab = () => {
+ const { isAdmin } = useAuth();
+
+ return (
+ <div className="api-settings">
+ <ApiKeysSection />
+ {isAdmin && <RateLimitsSection />}
+ <WebhookSection />
+ {isAdmin && <AnalyticsSection />}
+ </div>
+ );
+};
+
+// ─── API Keys Section ──────────────────────────────────
+const ApiKeysSection = () => {
+ const [keys, setKeys] = useState([]);
+ const [loading, setLoading] = useState(true);
+ const [showModal, setShowModal] = useState(false);
+ const [createdKey, setCreatedKey] = useState(null);
+
+ const loadKeys = () => {
+ setLoading(true);
+ api.getApiKeys().then(data => {
+ setKeys(data.api_keys || []);
+ }).catch(() => {}).finally(() => setLoading(false));
+ };
+
+ useEffect(() => { loadKeys(); }, []);
+
+ const handleCreate = async (data) => {
+ const result = await api.createApiKey(data);
+ setCreatedKey(result.raw_key);
+ loadKeys();
+ };
+
+ const handleRevoke = async (keyId) => {
+ if (!confirm('Revoke this API key? This cannot be undone.')) return;
+ await api.revokeApiKey(keyId);
+ loadKeys();
+ };
+
+ const handleRotate = async (keyId) => {
+ if (!confirm('Rotate this key? The old key will stop working immediately.')) return;
+ const result = await api.rotateApiKey(keyId);
+ setCreatedKey(result.raw_key);
+ setShowModal(true);
+ loadKeys();
+ };
+
+ const closeModal = () => {
+ setShowModal(false);
+ setCreatedKey(null);
+ };
+
+ return (
+ <div className="settings-card">
+ <div className="settings-card__header">
+ <div className="settings-card__header-left">
+ <Key size={20} />
+ <div>
+ <h3>API Keys</h3>
+ <p>Manage programmatic access to the ServerKit API</p>
+ </div>
+ </div>
+ <button className="btn btn-primary btn-sm" onClick={() => setShowModal(true)}>
+ <Plus size={14} /> Create Key
+ </button>
+ </div>
+
+ {loading ? (
+ <div className="settings-card__loading">Loading...</div>
+ ) : keys.length === 0 ? (
+ <div className="settings-card__empty">
+ <Key size={24} />
+ <p>No API keys yet. Create one to get started.</p>
+ </div>
+ ) : (
+ <div className="api-settings__table-wrap">
+ <table className="api-settings__table">
+ <thead>
+ <tr>
+ <th>Name</th>
+ <th>Key</th>
+ <th>Tier</th>
+ <th>Last Used</th>
+ <th>Status</th>
+ <th>Actions</th>
+ </tr>
+ </thead>
+ <tbody>
+ {keys.map(key => (
+ <tr key={key.id}>
+ <td className="api-settings__key-name">{key.name}</td>
+ <td><code className="api-settings__key-prefix">{key.key_prefix}...</code></td>
+ <td>
+ <span className={`badge badge--${key.tier}`}>{key.tier}</span>
+ </td>
+ <td className="api-settings__muted">
+ {key.last_used_at
+ ? new Date(key.last_used_at).toLocaleDateString()
+ : 'Never'}
+ </td>
+ <td>
+ {key.is_active && !key.revoked_at ? (
+ <span className="badge badge--success">Active</span>
+ ) : (
+ <span className="badge badge--danger">Revoked</span>
+ )}
+ </td>
+ <td className="api-settings__actions">
+ {key.is_active && !key.revoked_at && (
+ <>
+ <button
+ className="btn btn-sm btn-ghost"
+ onClick={() => handleRotate(key.id)}
+ title="Rotate"
+ >
+ <RotateCcw size={14} />
+ </button>
+ <button
+ className="btn btn-sm btn-ghost btn-danger"
+ onClick={() => handleRevoke(key.id)}
+ title="Revoke"
+ >
+ <Trash2 size={14} />
+ </button>
+ </>
+ )}
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ )}
+
+ {(showModal || createdKey) && (
+ <ApiKeyModal
+ onClose={closeModal}
+ onSubmit={handleCreate}
+ createdKey={createdKey}
+ />
+ )}
+ </div>
+ );
+};
+
+// ─── Rate Limits Section ───────────────────────────────
+const RateLimitsSection = () => {
+ const [limits, setLimits] = useState({
+ rate_limit_standard: '100 per minute',
+ rate_limit_elevated: '500 per minute',
+ rate_limit_unlimited: '5000 per minute',
+ rate_limit_unauthenticated: '30 per minute',
+ });
+ const [saving, setSaving] = useState(false);
+ const [message, setMessage] = useState(null);
+
+ useEffect(() => {
+ api.getSystemSettings().then(data => {
+ setLimits(prev => ({
+ rate_limit_standard: data.rate_limit_standard || prev.rate_limit_standard,
+ rate_limit_elevated: data.rate_limit_elevated || prev.rate_limit_elevated,
+ rate_limit_unlimited: data.rate_limit_unlimited || prev.rate_limit_unlimited,
+ rate_limit_unauthenticated: data.rate_limit_unauthenticated || prev.rate_limit_unauthenticated,
+ }));
+ }).catch(() => {});
+ }, []);
+
+ const handleSave = async () => {
+ setSaving(true);
+ setMessage(null);
+ try {
+ for (const [key, value] of Object.entries(limits)) {
+ await api.updateSystemSetting(key, value);
+ }
+ setMessage({ type: 'success', text: 'Rate limits updated' });
+ } catch {
+ setMessage({ type: 'error', text: 'Failed to update rate limits' });
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const labels = {
+ rate_limit_standard: 'Standard Tier',
+ rate_limit_elevated: 'Elevated Tier',
+ rate_limit_unlimited: 'Unlimited Tier',
+ rate_limit_unauthenticated: 'Unauthenticated',
+ };
+
+ return (
+ <div className="settings-card">
+ <div className="settings-card__header">
+ <div className="settings-card__header-left">
+ <Activity size={20} />
+ <div>
+ <h3>Rate Limits</h3>
+ <p>Configure request rate limits by tier</p>
+ </div>
+ </div>
+ </div>
+
+ {message && (
+ <div className={`alert alert--${message.type}`}>
+ {message.type === 'success' ? <Check size={16} /> : <AlertCircle size={16} />}
+ {message.text}
+ </div>
+ )}
+
+ <div className="api-settings__rate-limits">
+ {Object.entries(limits).map(([key, value]) => (
+ <div key={key} className="form-group form-group--inline">
+ <label>{labels[key]}</label>
+ <input
+ type="text"
+ className="form-input"
+ value={value}
+ onChange={e => setLimits(prev => ({ ...prev, [key]: e.target.value }))}
+ placeholder="e.g. 100 per minute"
+ />
+ </div>
+ ))}
+ </div>
+
+ <div className="settings-card__footer">
+ <button className="btn btn-primary" onClick={handleSave} disabled={saving}>
+ {saving ? 'Saving...' : 'Save Rate Limits'}
+ </button>
+ </div>
+ </div>
+ );
+};
+
+// ─── Webhook Subscriptions Section ─────────────────────
+const WebhookSection = () => {
+ const [subscriptions, setSubscriptions] = useState([]);
+ const [loading, setLoading] = useState(true);
+ const [showModal, setShowModal] = useState(false);
+ const [editingSub, setEditingSub] = useState(null);
+ const [expandedId, setExpandedId] = useState(null);
+ const [deliveries, setDeliveries] = useState({});
+
+ const loadSubscriptions = () => {
+ setLoading(true);
+ api.getEventSubscriptions().then(data => {
+ setSubscriptions(data.subscriptions || []);
+ }).catch(() => {}).finally(() => setLoading(false));
+ };
+
+ useEffect(() => { loadSubscriptions(); }, []);
+
+ const handleCreate = async (data) => {
+ await api.createEventSubscription(data);
+ setShowModal(false);
+ loadSubscriptions();
+ };
+
+ const handleUpdate = async (data) => {
+ await api.updateEventSubscription(editingSub.id, data);
+ setEditingSub(null);
+ loadSubscriptions();
+ };
+
+ const handleDelete = async (id) => {
+ if (!confirm('Delete this subscription?')) return;
+ await api.deleteEventSubscription(id);
+ loadSubscriptions();
+ };
+
+ const handleTest = async (id) => {
+ try {
+ await api.testEventSubscription(id);
+ loadDeliveries(id);
+ } catch { /* ignore */ }
+ };
+
+ const loadDeliveries = async (id) => {
+ try {
+ const data = await api.getEventDeliveries(id);
+ setDeliveries(prev => ({ ...prev, [id]: data.deliveries || [] }));
+ } catch { /* ignore */ }
+ };
+
+ const toggleExpand = (id) => {
+ if (expandedId === id) {
+ setExpandedId(null);
+ } else {
+ setExpandedId(id);
+ if (!deliveries[id]) loadDeliveries(id);
+ }
+ };
+
+ return (
+ <div className="settings-card">
+ <div className="settings-card__header">
+ <div className="settings-card__header-left">
+ <Zap size={20} />
+ <div>
+ <h3>Webhook Subscriptions</h3>
+ <p>Receive HTTP notifications when events occur</p>
+ </div>
+ </div>
+ <button className="btn btn-primary btn-sm" onClick={() => setShowModal(true)}>
+ <Plus size={14} /> Add Webhook
+ </button>
+ </div>
+
+ {loading ? (
+ <div className="settings-card__loading">Loading...</div>
+ ) : subscriptions.length === 0 ? (
+ <div className="settings-card__empty">
+ <Zap size={24} />
+ <p>No webhook subscriptions. Create one to get notified of events.</p>
+ </div>
+ ) : (
+ <div className="api-settings__webhooks">
+ {subscriptions.map(sub => (
+ <div key={sub.id} className="api-settings__webhook-card">
+ <div className="api-settings__webhook-header" onClick={() => toggleExpand(sub.id)}>
+ <div className="api-settings__webhook-info">
+ <span className="api-settings__webhook-name">{sub.name}</span>
+ <span className="api-settings__webhook-url">{sub.url}</span>
+ <div className="api-settings__webhook-events">
+ {sub.events.slice(0, 3).map(e => (
+ <span key={e} className="badge badge--subtle">{e}</span>
+ ))}
+ {sub.events.length > 3 && (
+ <span className="badge badge--subtle">+{sub.events.length - 3}</span>
+ )}
+ </div>
+ </div>
+ <div className="api-settings__webhook-controls">
+ <span className={`badge ${sub.is_active ? 'badge--success' : 'badge--danger'}`}>
+ {sub.is_active ? 'Active' : 'Inactive'}
+ </span>
+ {expandedId === sub.id ? <ChevronUp size={16} /> : <ChevronDown size={16} />}
+ </div>
+ </div>
+ {expandedId === sub.id && (
+ <div className="api-settings__webhook-details">
+ <div className="api-settings__webhook-actions">
+ <button className="btn btn-sm btn-secondary" onClick={() => handleTest(sub.id)}>
+ <Send size={14} /> Test
+ </button>
+ <button className="btn btn-sm btn-secondary" onClick={() => setEditingSub(sub)}>
+ Edit
+ </button>
+ <button className="btn btn-sm btn-ghost btn-danger" onClick={() => handleDelete(sub.id)}>
+ <Trash2 size={14} /> Delete
+ </button>
+ <button className="btn btn-sm btn-ghost" onClick={() => loadDeliveries(sub.id)}>
+ <RefreshCw size={14} />
+ </button>
+ </div>
+ {deliveries[sub.id] && (
+ <div className="api-settings__deliveries">
+ <h4>Recent Deliveries</h4>
+ {deliveries[sub.id].length === 0 ? (
+ <p className="api-settings__muted">No deliveries yet</p>
+ ) : (
+ <table className="api-settings__table api-settings__table--compact">
+ <thead>
+ <tr>
+ <th>Event</th>
+ <th>Status</th>
+ <th>HTTP</th>
+ <th>Duration</th>
+ <th>Time</th>
+ </tr>
+ </thead>
+ <tbody>
+ {deliveries[sub.id].slice(0, 10).map(d => (
+ <tr key={d.id}>
+ <td><code>{d.event_type}</code></td>
+ <td>
+ <span className={`badge badge--${d.status === 'success' ? 'success' : d.status === 'failed' ? 'danger' : 'warning'}`}>
+ {d.status}
+ </span>
+ </td>
+ <td>{d.http_status || '-'}</td>
+ <td>{d.duration_ms ? `${d.duration_ms}ms` : '-'}</td>
+ <td className="api-settings__muted">
+ {d.created_at ? new Date(d.created_at).toLocaleString() : '-'}
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ )}
+ </div>
+ )}
+ </div>
+ )}
+ </div>
+ ))}
+ </div>
+ )}
+
+ {showModal && (
+ <WebhookSubscriptionModal
+ onClose={() => setShowModal(false)}
+ onSubmit={handleCreate}
+ />
+ )}
+ {editingSub && (
+ <WebhookSubscriptionModal
+ subscription={editingSub}
+ onClose={() => setEditingSub(null)}
+ onSubmit={handleUpdate}
+ />
+ )}
+ </div>
+ );
+};
+
+// ─── Analytics Section ─────────────────────────────────
+const AnalyticsSection = () => {
+ const [overview, setOverview] = useState(null);
+ const [endpoints, setEndpoints] = useState([]);
+ const [timeseries, setTimeseries] = useState([]);
+ const [period, setPeriod] = useState('24h');
+ const [loading, setLoading] = useState(true);
+
+ const loadData = useCallback(() => {
+ setLoading(true);
+ Promise.all([
+ api.getApiAnalyticsOverview(period),
+ api.getApiAnalyticsEndpoints(period),
+ api.getApiAnalyticsTimeseries(period),
+ ]).then(([ov, ep, ts]) => {
+ setOverview(ov);
+ setEndpoints(ep.endpoints || []);
+ setTimeseries(ts.data || []);
+ }).catch(() => {}).finally(() => setLoading(false));
+ }, [period]);
+
+ useEffect(() => { loadData(); }, [loadData]);
+
+ const maxCount = Math.max(...timeseries.map(d => d.count), 1);
+
+ return (
+ <div className="settings-card">
+ <div className="settings-card__header">
+ <div className="settings-card__header-left">
+ <BarChart3 size={20} />
+ <div>
+ <h3>API Usage Analytics</h3>
+ <p>Monitor API traffic, response times, and errors</p>
+ </div>
+ </div>
+ <div className="api-settings__period-select">
+ {['1h', '24h', '7d', '30d'].map(p => (
+ <button
+ key={p}
+ className={`btn btn-sm ${period === p ? 'btn-primary' : 'btn-ghost'}`}
+ onClick={() => setPeriod(p)}
+ >
+ {p}
+ </button>
+ ))}
+ </div>
+ </div>
+
+ {loading ? (
+ <div className="settings-card__loading">Loading...</div>
+ ) : (
+ <>
+ {overview && (
+ <div className="api-settings__stats-grid">
+ <div className="api-settings__stat-card">
+ <span className="api-settings__stat-value">{overview.total_requests.toLocaleString()}</span>
+ <span className="api-settings__stat-label">Total Requests</span>
+ </div>
+ <div className="api-settings__stat-card">
+ <span className="api-settings__stat-value">{overview.avg_response_time_ms}ms</span>
+ <span className="api-settings__stat-label">Avg Response Time</span>
+ </div>
+ <div className="api-settings__stat-card">
+ <span className="api-settings__stat-value">{overview.error_rate}%</span>
+ <span className="api-settings__stat-label">Error Rate</span>
+ </div>
+ <div className="api-settings__stat-card">
+ <span className="api-settings__stat-value">{overview.success_count.toLocaleString()}</span>
+ <span className="api-settings__stat-label">Successful</span>
+ </div>
+ </div>
+ )}
+
+ {timeseries.length > 0 && (
+ <div className="api-settings__chart">
+ <h4>Request Volume</h4>
+ <div className="api-settings__bar-chart">
+ {timeseries.map((d, i) => (
+ <div key={i} className="api-settings__bar-col" title={`${d.period}: ${d.count} requests`}>
+ <div
+ className="api-settings__bar"
+ style={{ height: `${(d.count / maxCount) * 100}%` }}
+ />
+ {d.errors > 0 && (
+ <div
+ className="api-settings__bar api-settings__bar--error"
+ style={{ height: `${(d.errors / maxCount) * 100}%` }}
+ />
+ )}
+ </div>
+ ))}
+ </div>
+ </div>
+ )}
+
+ {endpoints.length > 0 && (
+ <div className="api-settings__top-endpoints">
+ <h4>Top Endpoints</h4>
+ <table className="api-settings__table api-settings__table--compact">
+ <thead>
+ <tr>
+ <th>Method</th>
+ <th>Endpoint</th>
+ <th>Requests</th>
+ <th>Avg Time</th>
+ <th>Errors</th>
+ </tr>
+ </thead>
+ <tbody>
+ {endpoints.slice(0, 10).map((ep, i) => (
+ <tr key={i}>
+ <td><span className={`badge badge--method badge--${ep.method.toLowerCase()}`}>{ep.method}</span></td>
+ <td><code>{ep.endpoint}</code></td>
+ <td>{ep.count.toLocaleString()}</td>
+ <td>{ep.avg_response_time_ms}ms</td>
+ <td>{ep.error_count > 0 ? <span className="api-settings__error-count">{ep.error_count}</span> : '-'}</td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ )}
+ </>
+ )}
+ </div>
+ );
+};
+
+export default ApiSettingsTab;
diff --git a/frontend/src/components/settings/WebhookSubscriptionModal.jsx b/frontend/src/components/settings/WebhookSubscriptionModal.jsx
new file mode 100644
index 00000000..2e95f95e
--- /dev/null
+++ b/frontend/src/components/settings/WebhookSubscriptionModal.jsx
@@ -0,0 +1,181 @@
+import { useState, useEffect } from 'react';
+import { X } from 'lucide-react';
+import api from '../../services/api';
+
+const WebhookSubscriptionModal = ({ subscription, onClose, onSubmit }) => {
+ const [name, setName] = useState('');
+ const [url, setUrl] = useState('');
+ const [selectedEvents, setSelectedEvents] = useState([]);
+ const [retryCount, setRetryCount] = useState(3);
+ const [timeoutSeconds, setTimeoutSeconds] = useState(10);
+ const [availableEvents, setAvailableEvents] = useState([]);
+ const [saving, setSaving] = useState(false);
+
+ useEffect(() => {
+ api.getAvailableEvents().then(data => {
+ setAvailableEvents(data.events || []);
+ }).catch(() => {});
+
+ if (subscription) {
+ setName(subscription.name || '');
+ setUrl(subscription.url || '');
+ setSelectedEvents(subscription.events || []);
+ setRetryCount(subscription.retry_count || 3);
+ setTimeoutSeconds(subscription.timeout_seconds || 10);
+ }
+ }, [subscription]);
+
+ const handleEventToggle = (eventType) => {
+ setSelectedEvents(prev =>
+ prev.includes(eventType)
+ ? prev.filter(e => e !== eventType)
+ : [...prev, eventType]
+ );
+ };
+
+ const handleCategoryToggle = (category) => {
+ const categoryEvents = availableEvents
+ .filter(e => e.category === category)
+ .map(e => e.type);
+ const allSelected = categoryEvents.every(e => selectedEvents.includes(e));
+ if (allSelected) {
+ setSelectedEvents(prev => prev.filter(e => !categoryEvents.includes(e)));
+ } else {
+ setSelectedEvents(prev => [...new Set([...prev, ...categoryEvents])]);
+ }
+ };
+
+ const handleSubmit = async (e) => {
+ e.preventDefault();
+ if (!name.trim() || !url.trim() || selectedEvents.length === 0) return;
+ setSaving(true);
+ try {
+ await onSubmit({
+ name: name.trim(),
+ url: url.trim(),
+ events: selectedEvents,
+ retry_count: retryCount,
+ timeout_seconds: timeoutSeconds,
+ });
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ // Group events by category
+ const groupedEvents = availableEvents.reduce((acc, event) => {
+ if (!acc[event.category]) acc[event.category] = [];
+ acc[event.category].push(event);
+ return acc;
+ }, {});
+
+ return (
+ <div className="modal-overlay" onClick={onClose}>
+ <div className="modal webhook-modal" onClick={e => e.stopPropagation()}>
+ <div className="modal-header">
+ <h3>{subscription ? 'Edit Subscription' : 'Create Webhook Subscription'}</h3>
+ <button className="modal-close" onClick={onClose}><X size={18} /></button>
+ </div>
+ <form onSubmit={handleSubmit}>
+ <div className="modal-body">
+ <div className="form-group">
+ <label>Name</label>
+ <input
+ type="text"
+ className="form-input"
+ value={name}
+ onChange={e => setName(e.target.value)}
+ placeholder="e.g. Slack Notifications, CI Trigger"
+ required
+ />
+ </div>
+
+ <div className="form-group">
+ <label>Payload URL</label>
+ <input
+ type="url"
+ className="form-input"
+ value={url}
+ onChange={e => setUrl(e.target.value)}
+ placeholder="https://example.com/webhook"
+ required
+ />
+ </div>
+
+ <div className="form-group">
+ <label>Events</label>
+ <div className="webhook-modal__events">
+ {Object.entries(groupedEvents).map(([category, events]) => {
+ const categoryEvents = events.map(e => e.type);
+ const allSelected = categoryEvents.every(e => selectedEvents.includes(e));
+ return (
+ <div key={category} className="webhook-modal__event-group">
+ <label className="webhook-modal__category">
+ <input
+ type="checkbox"
+ checked={allSelected}
+ onChange={() => handleCategoryToggle(category)}
+ />
+ <strong>{category}</strong>
+ </label>
+ <div className="webhook-modal__event-list">
+ {events.map(event => (
+ <label key={event.type} className="webhook-modal__event-item">
+ <input
+ type="checkbox"
+ checked={selectedEvents.includes(event.type)}
+ onChange={() => handleEventToggle(event.type)}
+ />
+ <span className="webhook-modal__event-type">{event.type}</span>
+ <span className="webhook-modal__event-desc">{event.description}</span>
+ </label>
+ ))}
+ </div>
+ </div>
+ );
+ })}
+ </div>
+ </div>
+
+ <div className="form-row">
+ <div className="form-group">
+ <label>Retry Count</label>
+ <input
+ type="number"
+ className="form-input"
+ value={retryCount}
+ onChange={e => setRetryCount(parseInt(e.target.value) || 3)}
+ min={0}
+ max={10}
+ />
+ </div>
+ <div className="form-group">
+ <label>Timeout (seconds)</label>
+ <input
+ type="number"
+ className="form-input"
+ value={timeoutSeconds}
+ onChange={e => setTimeoutSeconds(parseInt(e.target.value) || 10)}
+ min={1}
+ max={30}
+ />
+ </div>
+ </div>
+ </div>
+ <div className="modal-footer">
+ <button type="button" className="btn btn-secondary" onClick={onClose}>Cancel</button>
+ <button
+ type="submit"
+ className="btn btn-primary"
+ disabled={saving || !name.trim() || !url.trim() || selectedEvents.length === 0}
+ >
+ {saving ? 'Saving...' : (subscription ? 'Update' : 'Create')}
+ </button>
+ </div>
+ </form>
+ </div>
+ </div>
+ );
+};
+
+export default WebhookSubscriptionModal;
diff --git a/frontend/src/pages/Settings.jsx b/frontend/src/pages/Settings.jsx
index c3991049..dd7beac0 100644
--- a/frontend/src/pages/Settings.jsx
+++ b/frontend/src/pages/Settings.jsx
@@ -8,6 +8,7 @@ import UsersTab from '../components/settings/UsersTab';
import AuditLogTab from '../components/settings/AuditLogTab';
import SSOConfigTab from '../components/settings/SSOConfigTab';
import MigrationHistoryTab from '../components/settings/MigrationHistoryTab';
+import ApiSettingsTab from '../components/settings/ApiSettingsTab';
import SSOProviderIcon from '../components/SSOProviderIcon';
import {
Github, FileText, HelpCircle, MessageSquare, Bug, Check, Download, CheckCircle,
@@ -23,7 +24,7 @@ import {
} from 'lucide-react';
import ServerKitLogo from '../components/ServerKitLogo';
-const VALID_TABS = ['profile', 'security', 'appearance', 'notifications', 'system', 'users', 'audit', 'site', 'sso', 'migrations', 'developer', 'about'];
+const VALID_TABS = ['profile', 'security', 'appearance', 'notifications', 'system', 'users', 'audit', 'site', 'sso', 'api', 'migrations', 'developer', 'about'];
const Settings = () => {
const [activeTab, setActiveTab] = useTabParam('/settings', VALID_TABS);
@@ -156,6 +157,13 @@ const Settings = () => {
</svg>
SSO
</button>
+ <button
+ className={`settings-nav-item ${activeTab === 'api' ? 'active' : ''}`}
+ onClick={() => setActiveTab('api')}
+ >
+ <Code size={18} />
+ API
+ </button>
<button
className={`settings-nav-item ${activeTab === 'migrations' ? 'active' : ''}`}
onClick={() => setActiveTab('migrations')}
@@ -200,6 +208,7 @@ const Settings = () => {
{activeTab === 'audit' && isAdmin && <AuditLogTab />}
{activeTab === 'site' && isAdmin && <SiteSettings onDevModeChange={setDevMode} />}
{activeTab === 'sso' && isAdmin && <SSOConfigTab />}
+ {activeTab === 'api' && isAdmin && <ApiSettingsTab />}
{activeTab === 'migrations' && isAdmin && <MigrationHistoryTab />}
{activeTab === 'developer' && devMode && isAdmin && <IconReference />}
{activeTab === 'about' && <AboutSection />}
diff --git a/frontend/src/services/api.js b/frontend/src/services/api.js
index 75ccd0c9..2e0a39b5 100644
--- a/frontend/src/services/api.js
+++ b/frontend/src/services/api.js
@@ -3113,6 +3113,89 @@ class ApiService {
async getMigrationHistory() {
return this.request('/migrations/history');
}
+
+ // API Keys
+ async getApiKeys() {
+ return this.request('/api-keys/');
+ }
+
+ async createApiKey(data) {
+ return this.request('/api-keys/', { method: 'POST', body: data });
+ }
+
+ async getApiKey(id) {
+ return this.request(`/api-keys/${id}`);
+ }
+
+ async updateApiKey(id, data) {
+ return this.request(`/api-keys/${id}`, { method: 'PUT', body: data });
+ }
+
+ async revokeApiKey(id) {
+ return this.request(`/api-keys/${id}`, { method: 'DELETE' });
+ }
+
+ async rotateApiKey(id) {
+ return this.request(`/api-keys/${id}/rotate`, { method: 'POST' });
+ }
+
+ // Event Subscriptions (Webhooks)
+ async getEventSubscriptions() {
+ return this.request('/event-subscriptions/');
+ }
+
+ async createEventSubscription(data) {
+ return this.request('/event-subscriptions/', { method: 'POST', body: data });
+ }
+
+ async getAvailableEvents() {
+ return this.request('/event-subscriptions/events');
+ }
+
+ async getEventSubscription(id) {
+ return this.request(`/event-subscriptions/${id}`);
+ }
+
+ async updateEventSubscription(id, data) {
+ return this.request(`/event-subscriptions/${id}`, { method: 'PUT', body: data });
+ }
+
+ async deleteEventSubscription(id) {
+ return this.request(`/event-subscriptions/${id}`, { method: 'DELETE' });
+ }
+
+ async testEventSubscription(id) {
+ return this.request(`/event-subscriptions/${id}/test`, { method: 'POST' });
+ }
+
+ async getEventDeliveries(id, page = 1) {
+ return this.request(`/event-subscriptions/${id}/deliveries?page=${page}`);
+ }
+
+ async retryEventDelivery(subId, deliveryId) {
+ return this.request(`/event-subscriptions/${subId}/deliveries/${deliveryId}/retry`, { method: 'POST' });
+ }
+
+ // API Analytics
+ async getApiAnalyticsOverview(period = '24h') {
+ return this.request(`/api-analytics/overview?period=${period}`);
+ }
+
+ async getApiAnalyticsEndpoints(period = '24h', limit = 20) {
+ return this.request(`/api-analytics/endpoints?period=${period}&limit=${limit}`);
+ }
+
+ async getApiAnalyticsErrors(period = '24h') {
+ return this.request(`/api-analytics/errors?period=${period}`);
+ }
+
+ async getApiAnalyticsTimeseries(period = '24h', interval = 'hour') {
+ return this.request(`/api-analytics/timeseries?period=${period}&interval=${interval}`);
+ }
+
+ async getApiKeyUsage(keyId, period = '24h') {
+ return this.request(`/api-analytics/keys/${keyId}/usage?period=${period}`);
+ }
}
export const api = new ApiService();
diff --git a/frontend/src/styles/components/_api-settings.less b/frontend/src/styles/components/_api-settings.less
new file mode 100644
index 00000000..c39465ba
--- /dev/null
+++ b/frontend/src/styles/components/_api-settings.less
@@ -0,0 +1,530 @@
+// ============================================
+// API Settings Styles
+// ============================================
+
+.api-settings {
+ display: flex;
+ flex-direction: column;
+ gap: @space-6;
+}
+
+// ─── Tables ────────────────────────────────────────────
+
+.api-settings__table-wrap {
+ overflow-x: auto;
+}
+
+.api-settings__table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: @font-size-sm;
+
+ th, td {
+ padding: @space-2 @space-3;
+ text-align: left;
+ border-bottom: 1px solid @border-subtle;
+ }
+
+ th {
+ color: @text-secondary;
+ font-weight: 500;
+ font-size: @font-size-xs;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ }
+
+ td {
+ color: @text-primary;
+ }
+
+ tbody tr:hover {
+ background: @bg-hover;
+ }
+
+ code {
+ font-family: @font-mono;
+ font-size: @font-size-xs;
+ padding: 2px 6px;
+ background: @bg-elevated;
+ border-radius: @radius-sm;
+ }
+
+ &--compact {
+ th, td {
+ padding: @space-1 @space-2;
+ }
+ }
+}
+
+.api-settings__key-name {
+ font-weight: 500;
+}
+
+.api-settings__key-prefix {
+ font-family: @font-mono;
+}
+
+.api-settings__muted {
+ color: @text-tertiary;
+ font-size: @font-size-xs;
+}
+
+.api-settings__actions {
+ display: flex;
+ gap: @space-1;
+}
+
+.api-settings__error-count {
+ color: @danger;
+ font-weight: 600;
+}
+
+// ─── Rate Limits ───────────────────────────────────────
+
+.api-settings__rate-limits {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: @space-4;
+ padding: @space-4;
+
+ .form-group--inline {
+ display: flex;
+ flex-direction: column;
+ gap: @space-1;
+
+ label {
+ font-size: @font-size-sm;
+ font-weight: 500;
+ color: @text-secondary;
+ }
+ }
+}
+
+// ─── Webhook Cards ─────────────────────────────────────
+
+.api-settings__webhooks {
+ display: flex;
+ flex-direction: column;
+ gap: @space-2;
+ padding: @space-2;
+}
+
+.api-settings__webhook-card {
+ border: 1px solid @border-subtle;
+ border-radius: @radius-md;
+ overflow: hidden;
+}
+
+.api-settings__webhook-header {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ padding: @space-3 @space-4;
+ cursor: pointer;
+ transition: background 0.15s;
+
+ &:hover {
+ background: @bg-hover;
+ }
+}
+
+.api-settings__webhook-info {
+ display: flex;
+ flex-direction: column;
+ gap: @space-1;
+ min-width: 0;
+}
+
+.api-settings__webhook-name {
+ font-weight: 600;
+ color: @text-primary;
+}
+
+.api-settings__webhook-url {
+ font-family: @font-mono;
+ font-size: @font-size-xs;
+ color: @text-tertiary;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+
+.api-settings__webhook-events {
+ display: flex;
+ flex-wrap: wrap;
+ gap: @space-1;
+ margin-top: @space-1;
+}
+
+.api-settings__webhook-controls {
+ display: flex;
+ align-items: center;
+ gap: @space-2;
+ flex-shrink: 0;
+}
+
+.api-settings__webhook-details {
+ border-top: 1px solid @border-subtle;
+ padding: @space-3 @space-4;
+}
+
+.api-settings__webhook-actions {
+ display: flex;
+ gap: @space-2;
+ margin-bottom: @space-3;
+}
+
+.api-settings__deliveries {
+ h4 {
+ font-size: @font-size-sm;
+ color: @text-secondary;
+ margin-bottom: @space-2;
+ }
+}
+
+// ─── Analytics ─────────────────────────────────────────
+
+.api-settings__period-select {
+ display: flex;
+ gap: @space-1;
+}
+
+.api-settings__stats-grid {
+ display: grid;
+ grid-template-columns: repeat(4, 1fr);
+ gap: @space-3;
+ padding: @space-4;
+}
+
+.api-settings__stat-card {
+ display: flex;
+ flex-direction: column;
+ gap: @space-1;
+ padding: @space-3;
+ background: @bg-elevated;
+ border-radius: @radius-md;
+ text-align: center;
+}
+
+.api-settings__stat-value {
+ font-size: @font-size-xl;
+ font-weight: 700;
+ color: @text-primary;
+}
+
+.api-settings__stat-label {
+ font-size: @font-size-xs;
+ color: @text-tertiary;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+}
+
+.api-settings__chart {
+ padding: @space-4;
+
+ h4 {
+ font-size: @font-size-sm;
+ color: @text-secondary;
+ margin-bottom: @space-3;
+ }
+}
+
+.api-settings__bar-chart {
+ display: flex;
+ align-items: flex-end;
+ gap: 2px;
+ height: 120px;
+ padding: @space-2 0;
+}
+
+.api-settings__bar-col {
+ flex: 1;
+ display: flex;
+ flex-direction: column;
+ align-items: stretch;
+ justify-content: flex-end;
+ height: 100%;
+ min-width: 4px;
+}
+
+.api-settings__bar {
+ background: @accent-primary;
+ border-radius: @radius-sm @radius-sm 0 0;
+ min-height: 2px;
+ transition: height 0.3s ease;
+
+ &--error {
+ background: @danger;
+ border-radius: 0;
+ }
+}
+
+.api-settings__top-endpoints {
+ padding: @space-4;
+
+ h4 {
+ font-size: @font-size-sm;
+ color: @text-secondary;
+ margin-bottom: @space-2;
+ }
+}
+
+// ─── Method Badges ─────────────────────────────────────
+
+.badge--method {
+ font-family: @font-mono;
+ font-size: @font-size-xs;
+ font-weight: 600;
+ padding: 1px 6px;
+ border-radius: @radius-sm;
+}
+
+.badge--get {
+ background: @success-bg;
+ color: @success;
+}
+
+.badge--post {
+ background: @info-bg;
+ color: @info;
+}
+
+.badge--put {
+ background: @warning-bg;
+ color: @warning;
+}
+
+.badge--delete {
+ background: @danger-bg;
+ color: @danger;
+}
+
+.badge--patch {
+ background: @info-bg;
+ color: @info;
+}
+
+// ─── Tier Badges ───────────────────────────────────────
+
+.badge--standard {
+ background: @bg-elevated;
+ color: @text-secondary;
+}
+
+.badge--elevated {
+ background: @info-bg;
+ color: @info;
+}
+
+.badge--unlimited {
+ background: @warning-bg;
+ color: @warning;
+}
+
+.badge--subtle {
+ background: @bg-elevated;
+ color: @text-secondary;
+ font-size: @font-size-xs;
+ padding: 1px 6px;
+ border-radius: @radius-sm;
+}
+
+// ─── API Key Modal ─────────────────────────────────────
+
+.api-key-modal {
+ max-width: 520px;
+
+ .api-key-modal__warning {
+ display: flex;
+ align-items: center;
+ gap: @space-2;
+ padding: @space-3;
+ background: @warning-bg;
+ border: 1px solid @warning-border;
+ border-radius: @radius-md;
+ color: @warning;
+ font-size: @font-size-sm;
+ margin-bottom: @space-4;
+ }
+
+ .api-key-modal__key-display {
+ display: flex;
+ align-items: center;
+ gap: @space-2;
+ padding: @space-3;
+ background: @bg-elevated;
+ border-radius: @radius-md;
+ overflow-x: auto;
+
+ code {
+ flex: 1;
+ font-family: @font-mono;
+ font-size: @font-size-sm;
+ word-break: break-all;
+ }
+ }
+
+ .api-key-modal__tiers {
+ display: grid;
+ grid-template-columns: repeat(3, 1fr);
+ gap: @space-2;
+ }
+
+ .api-key-modal__tier-btn {
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ gap: @space-1;
+ padding: @space-3;
+ border: 1px solid @border-subtle;
+ border-radius: @radius-md;
+ background: transparent;
+ color: @text-secondary;
+ cursor: pointer;
+ transition: all 0.15s;
+
+ &:hover {
+ border-color: @border-default;
+ background: @bg-hover;
+ }
+
+ &.active {
+ border-color: @accent-primary;
+ background: fade(@accent-primary-raw, 8%);
+ color: @accent-primary;
+ }
+ }
+
+ .api-key-modal__tier-label {
+ font-weight: 600;
+ font-size: @font-size-sm;
+ }
+
+ .api-key-modal__tier-desc {
+ font-size: @font-size-xs;
+ opacity: 0.7;
+ }
+
+ .api-key-modal__scopes {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: @space-1;
+ max-height: 200px;
+ overflow-y: auto;
+ padding: @space-2;
+ border: 1px solid @border-subtle;
+ border-radius: @radius-md;
+ }
+
+ .api-key-modal__scope-item {
+ display: flex;
+ align-items: center;
+ gap: @space-2;
+ font-size: @font-size-sm;
+ padding: @space-1;
+ cursor: pointer;
+
+ &:hover {
+ background: @bg-hover;
+ border-radius: @radius-sm;
+ }
+
+ input[type="checkbox"] {
+ accent-color: @accent-primary;
+ }
+ }
+}
+
+// ─── Webhook Modal ─────────────────────────────────────
+
+.webhook-modal {
+ max-width: 600px;
+
+ .webhook-modal__events {
+ max-height: 300px;
+ overflow-y: auto;
+ border: 1px solid @border-subtle;
+ border-radius: @radius-md;
+ padding: @space-2;
+ }
+
+ .webhook-modal__event-group {
+ margin-bottom: @space-2;
+
+ &:last-child {
+ margin-bottom: 0;
+ }
+ }
+
+ .webhook-modal__category {
+ display: flex;
+ align-items: center;
+ gap: @space-2;
+ padding: @space-1;
+ cursor: pointer;
+ font-size: @font-size-sm;
+
+ input[type="checkbox"] {
+ accent-color: @accent-primary;
+ }
+ }
+
+ .webhook-modal__event-list {
+ padding-left: @space-6;
+ }
+
+ .webhook-modal__event-item {
+ display: flex;
+ align-items: center;
+ gap: @space-2;
+ padding: @space-1;
+ cursor: pointer;
+ font-size: @font-size-sm;
+
+ &:hover {
+ background: @bg-hover;
+ border-radius: @radius-sm;
+ }
+
+ input[type="checkbox"] {
+ accent-color: @accent-primary;
+ }
+ }
+
+ .webhook-modal__event-type {
+ font-family: @font-mono;
+ font-size: @font-size-xs;
+ color: @text-primary;
+ }
+
+ .webhook-modal__event-desc {
+ color: @text-tertiary;
+ font-size: @font-size-xs;
+ }
+
+ .form-row {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: @space-4;
+ }
+}
+
+// ─── Responsive ────────────────────────────────────────
+
+@media (max-width: 768px) {
+ .api-settings__stats-grid {
+ grid-template-columns: repeat(2, 1fr);
+ }
+
+ .api-settings__rate-limits {
+ grid-template-columns: 1fr;
+ }
+
+ .api-key-modal__tiers {
+ grid-template-columns: 1fr;
+ }
+
+ .api-key-modal__scopes {
+ grid-template-columns: 1fr;
+ }
+}
diff --git a/frontend/src/styles/main.less b/frontend/src/styles/main.less
index e99d1b2f..30a24975 100644
--- a/frontend/src/styles/main.less
+++ b/frontend/src/styles/main.less
@@ -51,6 +51,7 @@
@import 'components/_build';
@import 'components/_users';
@import 'components/_linked-apps';
+@import 'components/_api-settings';
// --------------------------------------------
// 5. PAGE-SPECIFIC STYLES