Platform Settings API

REST API endpoints for platform settings management.

Table of Contents

  1. Overview
    1. Base URL
    2. Authentication
    3. Common Response Format
  2. Endpoints
    1. 1. Get All Settings
    2. 2. Get Settings Section
    3. 3. Update All Settings
    4. 4. Update Settings Section
    5. 5. Export Settings
    6. 6. Import Settings
  3. Validation Rules
    1. General Settings
    2. Branding Settings
    3. Course Settings
    4. AI Settings
    5. User Settings
    6. Payment Settings
    7. Analytics Settings
  4. Error Codes
  5. Rate Limiting
  6. Caching
  7. Security Considerations
    1. Authentication
    2. Authorization
    3. Input Sanitization
    4. Audit Trail
    5. Sensitive Data
  8. Performance
  9. TypeScript Types
  10. Related Documentation
  11. Changelog
    1. Version 1.0.0 (2025-12-23)

Overview

The Settings API provides endpoints for administrators to manage platform-wide configuration settings. All endpoints require admin authentication via AWS Cognito JWT tokens.

Base URL 

https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev

Authentication

All settings endpoints require:

  • Valid JWT token in Authorization header
  • User must be in admin Cognito group
Authorization: Bearer eyJraWQiOiJ...

Common Response Format

Success Response:

{
  "general": {
    "platform_name": "Momentum",
    "support_email": "support@momentum.com"
  }
}

Error Response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "general.platform_name",
        "message": "Platform name is required"
      }
    ]
  }
}

Endpoints

1. Get All Settings

Retrieve all platform settings across all sections.

Endpoint:

GET /admin/settings

Authentication: Required (Admin)

Query Parameters: None

Response:

{
  "general": {
    "platform_name": "Momentum",
    "platform_tagline": "Learn anything, achieve everything",
    "support_email": "support@momentum.com",
    "default_timezone": "America/New_York",
    "maintenance_mode": false,
    "maintenance_message": "",
    "default_language": "en"
  },
  "branding": {
    "primary_color": "#3b82f6",
    "secondary_color": "#8b5cf6",
    "accent_color": "#f59e0b",
    "logo_url": "",
    "logo_dark_url": "",
    "favicon_url": "",
    "custom_css": "",
    "custom_footer_html": ""
  },
  "courses": {
    "default_duration": 14,
    "max_duration": 21,
    "min_duration": 7,
    "auto_enroll_new_users": false,
    "allow_self_enrollment": true
  },
  "ai": {
    "default_model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "max_tokens": 8000,
    "temperature": 0.7,
    "enable_video_generation": true,
    "video_provider": "heygen"
  },
  "user": {
    "allow_registration": true,
    "require_email_verification": true,
    "default_role": "free",
    "session_timeout": 86400,
    "max_login_attempts": 5
  },
  "payment": {
    "stripe_enabled": true,
    "currency": "USD",
    "trial_period_days": 7,
    "allow_refunds": true
  },
  "analytics": {
    "enable_tracking": true,
    "retention_days": 90,
    "track_page_views": true,
    "track_user_actions": true
  }
}

Status Codes:

  • 200 OK - Settings retrieved successfully
  • 401 Unauthorized - Missing or invalid JWT token
  • 403 Forbidden - User is not an admin
  • 500 Internal Server Error - Server error

Example Request:

curl -X GET "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Caching: Results are cached in Redis for 5 minutes.

2. Get Settings Section

Retrieve settings for a specific section only.

Endpoint:

GET /admin/settings/{section}

Authentication: Required (Admin)

Path Parameters:

Parameter Type Required Description
section string Yes Section name: general, branding, courses, ai, user, payment, analytics

Response:

{
  "platform_name": "Momentum",
  "platform_tagline": "Learn anything, achieve everything",
  "support_email": "support@momentum.com",
  "default_timezone": "America/New_York",
  "maintenance_mode": false,
  "maintenance_message": "",
  "default_language": "en"
}

Status Codes:

  • 200 OK - Section retrieved successfully
  • 400 Bad Request - Invalid section name
  • 401 Unauthorized - Missing or invalid JWT token
  • 403 Forbidden - User is not an admin
  • 404 Not Found - Section does not exist
  • 500 Internal Server Error - Server error

Example Request:

curl -X GET "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings/general" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

3. Update All Settings

Update all platform settings (full replacement).

Endpoint:

PUT /admin/settings

Authentication: Required (Admin)

Request Body:

Complete settings object with all sections. Any section not included will be reset to defaults.

{
  "general": {
    "platform_name": "My Learning Platform",
    "platform_tagline": "Custom tagline",
    "support_email": "support@example.com",
    "default_timezone": "America/Los_Angeles",
    "maintenance_mode": false,
    "maintenance_message": "",
    "default_language": "en"
  },
  "branding": {
    "primary_color": "#3b82f6",
    "secondary_color": "#8b5cf6",
    "accent_color": "#f59e0b",
    "logo_url": "https://cdn.example.com/logo.png",
    "logo_dark_url": "https://cdn.example.com/logo-dark.png",
    "favicon_url": "https://cdn.example.com/favicon.ico",
    "custom_css": "",
    "custom_footer_html": ""
  }
  // ... other sections
}

Response:

{
  "message": "Settings updated successfully"
}

Status Codes:

  • 200 OK - Settings updated successfully
  • 400 Bad Request - Invalid request body or validation error
  • 401 Unauthorized - Missing or invalid JWT token
  • 403 Forbidden - User is not an admin
  • 500 Internal Server Error - Server error

Example Request:

curl -X PUT "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "general": {
      "platform_name": "My Platform"
    }
  }'

Note: This endpoint performs a full replacement. Use PATCH for partial updates.

4. Update Settings Section

Update a specific settings section (partial update).

Endpoint:

PATCH /admin/settings/{section}

Authentication: Required (Admin)

Path Parameters:

Parameter Type Required Description
section string Yes Section name: general, branding, courses, ai, user, payment, analytics

Request Body:

Partial settings object. Only include fields you want to update.

{
  "platform_name": "Updated Platform Name",
  "maintenance_mode": true,
  "maintenance_message": "System maintenance in progress"
}

Response:

{
  "message": "Settings section 'general' updated successfully"
}

Status Codes:

  • 200 OK - Section updated successfully
  • 400 Bad Request - Invalid section or validation error
  • 401 Unauthorized - Missing or invalid JWT token
  • 403 Forbidden - User is not an admin
  • 404 Not Found - Section does not exist
  • 500 Internal Server Error - Server error

Example Requests:

Update General Settings:

curl -X PATCH "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings/general" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_name": "Momentum Learning",
    "support_email": "help@momentum.com"
  }'

Update Branding Colors:

curl -X PATCH "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings/branding" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_color": "#1e40af",
    "secondary_color": "#7c3aed"
  }'

Enable Maintenance Mode:

curl -X PATCH "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings/general" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "maintenance_mode": true,
    "maintenance_message": "Scheduled maintenance 10 PM - 11 PM EST"
  }'

Update AI Settings:

curl -X PATCH "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings/ai" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "temperature": 0.8,
    "max_tokens": 10000
  }'

5. Export Settings

Export all settings as a JSON file with metadata.

Endpoint:

POST /admin/settings/export

Authentication: Required (Admin)

Request Body: None

Response:

{
  "version": "1.0.0",
  "exported_at": "2025-12-23T10:30:00.000Z",
  "exported_by": "admin@momentum.com",
  "settings": {
    "general": {
      "platform_name": "Momentum",
      "platform_tagline": "Learn anything, achieve everything",
      "support_email": "support@momentum.com",
      "default_timezone": "America/New_York",
      "maintenance_mode": false,
      "maintenance_message": "",
      "default_language": "en"
    },
    "branding": { /* ... */ },
    "courses": { /* ... */ },
    "ai": { /* ... */ },
    "user": { /* ... */ },
    "payment": { /* ... */ },
    "analytics": { /* ... */ }
  }
}

Status Codes:

  • 200 OK - Settings exported successfully
  • 401 Unauthorized - Missing or invalid JWT token
  • 403 Forbidden - User is not an admin
  • 500 Internal Server Error - Server error

Example Request:

curl -X POST "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings/export" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  > momentum-settings-backup.json

Frontend Usage:

The frontend automatically formats the filename as momentum-settings-[timestamp].json when downloaded via the browser.

6. Import Settings

Import settings from a JSON file (replace or merge mode).

Endpoint:

POST /admin/settings/import

Authentication: Required (Admin)

Query Parameters:

Parameter Type Required Default Description
merge_mode boolean No false If true, merge with existing settings. If false, replace all settings.

Request Body:

Settings export object (must include version and settings).

{
  "version": "1.0.0",
  "settings": {
    "general": {
      "platform_name": "Imported Platform",
      "support_email": "imported@example.com"
    },
    "branding": {
      "primary_color": "#ef4444"
    }
  }
}

Response:

{
  "message": "Settings imported successfully",
  "mode": "merge"
}

Status Codes:

  • 200 OK - Settings imported successfully
  • 400 Bad Request - Invalid import format or validation error
  • 401 Unauthorized - Missing or invalid JWT token
  • 403 Forbidden - User is not an admin
  • 422 Unprocessable Entity - Version mismatch or invalid data
  • 500 Internal Server Error - Server error

Import Modes:

Replace Mode (default - merge_mode=false):

  • Replaces ALL existing settings
  • Settings not in import file are reset to defaults
  • Use for complete environment restoration

Merge Mode (merge_mode=true):

  • Updates only settings present in import file
  • Preserves existing settings not in import
  • Use for partial updates or migrations

Example Requests:

Replace Mode (Full Import):

curl -X POST "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings/import" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @momentum-settings-backup.json

Merge Mode (Partial Import):

curl -X POST "https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/admin/settings/import?merge_mode=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "settings": {
      "general": {
        "platform_name": "New Name"
      }
    }
  }'

Validation: All imported settings are validated and sanitized before being saved.

Validation Rules

General Settings

Field Type Validation
platform_name string Required, 1-100 chars
platform_tagline string Optional, max 200 chars
support_email string Required, valid email format
default_timezone string Required, valid IANA timezone
default_language string Required, ISO 639-1 code (2 chars)
maintenance_mode boolean Required
maintenance_message string Optional, max 500 chars

Branding Settings

Field Type Validation
primary_color string Required, hex format #RRGGBB
secondary_color string Required, hex format #RRGGBB
accent_color string Required, hex format #RRGGBB
logo_url string Optional, valid URL
logo_dark_url string Optional, valid URL
favicon_url string Optional, valid URL
custom_css string Optional, max 10,000 chars
custom_footer_html string Optional, max 5,000 chars, sanitized

Course Settings

Field Type Validation
default_duration number Optional, 7-21
min_duration number Optional, 7-21
max_duration number Optional, 7-21
auto_enroll_new_users boolean Optional
allow_self_enrollment boolean Optional

AI Settings

Field Type Validation
default_model string Optional, valid Bedrock model ID
max_tokens number Optional, 100-100,000
temperature number Optional, 0.0-1.0
enable_video_generation boolean Optional
video_provider string Optional, one of: heygen, synthesia, d-id

User Settings

Field Type Validation
allow_registration boolean Optional
require_email_verification boolean Optional
default_role string Optional, one of: free, premium, admin
session_timeout number Optional, 300-604800 (5 min - 7 days)
max_login_attempts number Optional, 3-10

Payment Settings

Field Type Validation
stripe_enabled boolean Optional
currency string Optional, ISO 4217 currency code
trial_period_days number Optional, 0-30
allow_refunds boolean Optional

Analytics Settings

Field Type Validation
enable_tracking boolean Optional
retention_days number Optional, 1-365
track_page_views boolean Optional
track_user_actions boolean Optional

Error Codes

Code HTTP Status Description
AUTHENTICATION_ERROR 401 Missing or invalid JWT token
AUTHORIZATION_ERROR 403 User is not an admin
VALIDATION_ERROR 400 Input validation failed
NOT_FOUND 404 Resource not found
INTERNAL_ERROR 500 Server error

Validation Error Example:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "branding.primary_color",
        "message": "Must be a valid hex color (#RRGGBB)"
      },
      {
        "field": "ai.temperature",
        "message": "Must be between 0 and 1"
      }
    ]
  }
}

Rate Limiting

Current Limits:

  • No explicit rate limiting implemented
  • AWS API Gateway throttling applies (10,000 requests/second burst)
  • Lambda concurrency limits apply (1,000 concurrent executions)

Best Practices:

  • Cache GET requests on client side
  • Batch updates when possible (use PUT instead of multiple PATCH)
  • Implement exponential backoff for retries

Caching

Redis Cache:

  • TTL: 5 minutes
  • Key: platform:settings
  • Invalidation: Automatic on any update (PUT/PATCH/POST import)

Client-Side Caching:

  • Cache GET responses for 1-5 minutes
  • Invalidate on mutations
  • Use ETag/If-None-Match headers if implemented

Security Considerations

Authentication

  • All endpoints require valid Cognito JWT token
  • Token must contain cognito:groups claim with admin value
  • Tokens expire after session timeout (configurable, default 24 hours)

Authorization

  • Admin role verified on every request
  • User ID extracted from sub claim for audit trail
  • Email extracted from email claim for export metadata

Input Sanitization

  • All string inputs sanitized to prevent XSS
  • HTML tags removed from most fields
  • Custom CSS and footer HTML are allowed but sanitized
  • URLs validated for proper format
  • SQL injection prevented via parameterized queries

Audit Trail

All mutations logged to platform_settings_audit table:

SELECT * FROM platform_settings_audit
WHERE changed_at > NOW() - INTERVAL '7 days'
ORDER BY changed_at DESC;

Logged Information:

  • Setting ID, section, key
  • Old value and new value
  • Changed by (user ID)
  • Changed at (timestamp)

Sensitive Data

Export files may contain:

  • Email addresses
  • API configuration
  • Brand assets URLs
  • Custom CSS/HTML

Recommendation: Encrypt export files if storing externally or transmitting.

Performance

Response Times (P95):

  • GET all settings: ~100-150ms (cached: ~10-20ms)
  • GET section: ~50-100ms (cached: ~10-20ms)
  • PATCH section: ~200-300ms
  • PUT all settings: ~500-800ms
  • Export: ~150-250ms
  • Import: ~500-1000ms (depends on size)

Database Queries:

  • GET: 1 query (SELECT all settings)
  • PATCH: 1-10 queries (1 per changed setting)
  • PUT: 20-50 queries (1 per setting)
  • Import: Varies by settings count

Optimization Tips:

  • Use PATCH for single section updates
  • Use Redis cache for read-heavy workloads
  • Batch updates when possible
  • Monitor CloudWatch metrics for Lambda cold starts

TypeScript Types

For TypeScript projects, use the following types:

// Settings sections
export interface GeneralSettings {
  platform_name: string;
  platform_tagline?: string;
  default_timezone: string;
  maintenance_mode: boolean;
  maintenance_message?: string;
  support_email: string;
  default_language: string;
}

export interface BrandingSettings {
  primary_color: string;
  secondary_color: string;
  accent_color: string;
  logo_url?: string;
  logo_dark_url?: string;
  favicon_url?: string;
  custom_css?: string;
  custom_footer_html?: string;
}

// Complete settings state
export interface SettingsState {
  general: GeneralSettings;
  branding: BrandingSettings;
  courses: CourseSettings;
  ai: AISettings;
  user: UserSettings;
  payment: PaymentSettings;
  analytics: AnalyticsSettings;
}

// Export format
export interface SettingsExport {
  version: string;
  exported_at: string;
  exported_by: string;
  settings: SettingsState;
}

See backend/functions/settings/src/types/settings.types.ts for complete type definitions.

Changelog

Version 1.0.0 (2025-12-23)

  • Initial release
  • 6 endpoints (GET, PATCH, PUT, Export, Import)
  • 7 settings sections
  • Redis caching
  • Audit trail
  • Import/export functionality

Back to top

Momentum LMS © 2025. Distributed under the MIT license.