Admin Preferences API Documentation

Overview

The Admin Preferences API provides endpoints for managing all platform-wide configuration settings. This system allows administrators to configure authentication, GDPR compliance, feature flags, localization, and operational parameters without developer intervention.

Base URL

/api/admin/preferences

Authentication

All endpoints require:

  • Valid JWT access token
  • Admin role (user.role === 'admin')

Include the token in the Authorization header:

Authorization: Bearer <access_token>

Endpoints

Get Admin Preferences

Retrieves all current admin preferences.

Endpoint: GET /api/admin/preferences

Headers:

Authorization: Bearer <access_token>

Response: 200 OK

{
  "id": "00000000-0000-0000-0000-000000000001",
  
  "admin_2fa_enforcement": true,
  "session_timeout_minutes": 720,
  "password_min_length": 12,
  "password_require_special": true,
  "password_require_numbers": true,
  "password_require_uppercase": true,
  "max_login_attempts": 5,
  "account_lockout_duration_minutes": 30,
  
  "auth_log_retention_months": 13,
  "admin_log_retention_months": 25,
  "enable_audit_logging": true,
  "enable_pseudonymization": false,
  
  "environment": "production",
  
  "from_email": "noreply@conformo.ai",
  "trusted_domains": ["example.com", "company.it"],
  
  "show_landing_page": true,
  "collect_emails": true,
  "show_pricing": true,
  "user_registration": true,
  "gdpr_questionnaire": false,
  "risk_scoring": false,
  "subscriptions": false,
  
  "default_locale": "it-IT",
  "default_timezone": "Europe/Rome",
  "timestamp_format": "dd/MM/yyyy HH:mm",
  
  "max_export_rows": 10000,
  "default_export_filename_prefix": "conformo_export",
  "enable_csv_export": true,
  "enable_pdf_export": false,
  
  "enable_right_to_erasure": true,
  "enable_retention_enforcement": true,
  "auto_cleanup_enabled": true,
  "cleanup_schedule_day": 0,
  "cleanup_schedule_hour": 2,
  
  "enable_rate_limiting": true,
  "rate_limit_window_minutes": 15,
  "rate_limit_max_requests": 100,
  "enable_webhook_integrations": false,
  "webhook_urls": null,
  
  "updated_by": "user-uuid",
  "updated_at": "2025-10-17T20:00:00.000Z",
  "created_at": "2025-10-01T00:00:00.000Z"
}

Error Responses:

  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - User is not an admin
  • 500 Internal Server Error - Server error

Update Admin Preferences

Updates one or more admin preference settings.

Endpoint: PUT /api/admin/preferences

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body:

{
  "password_min_length": 14,
  "admin_2fa_enforcement": true,
  "max_export_rows": 50000
}

Note: You can update any combination of fields. Only include the fields you want to change.

Response: 200 OK

{
  "success": true,
  "message": "Preferenze aggiornate con successo",
  "preferences": {
    "id": "00000000-0000-0000-0000-000000000001",
    // ... all preferences with updated values
  }
}

Error Responses:

  • 400 Bad Request - Invalid field values or validation errors 
    {
  "error": "Lunghezza minima password deve essere tra 8 e 128 caratteri"
}
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - User is not an admin
  • 404 Not Found - Preferences record not found
  • 500 Internal Server Error - Server error

Preference Fields Reference

Authentication & Security

Field Type Range/Options Default Description
admin_2fa_enforcement boolean - true Require 2FA for all admin users
session_timeout_minutes number 5-43200 720 Session timeout in minutes
password_min_length number 8-128 12 Minimum password length
password_require_special boolean - true Require special characters
password_require_numbers boolean - true Require numbers
password_require_uppercase boolean - true Require uppercase letters
max_login_attempts number 3-20 5 Max failed login attempts
account_lockout_duration_minutes number 5-1440 30 Account lockout duration

Audit Logging & GDPR

Field Type Range/Options Default Description
auth_log_retention_months number 1-120 13 Auth log retention period
admin_log_retention_months number 1-120 25 Admin log retention period
enable_audit_logging boolean - true Enable audit logging
enable_pseudonymization boolean - false Enable pseudonymization

Environment

Field Type Range/Options Default Description
environment string development, staging, production production Current environment

Email & Notifications

Field Type Range/Options Default Description
from_email string Valid email noreply@conformo.ai Sender email address
trusted_domains string[] - null Trusted email domains

Feature Flags

Field Type Range/Options Default Description
show_landing_page boolean - true Show landing page
collect_emails boolean - true Collect emails
show_pricing boolean - true Show pricing section
user_registration boolean - true Enable user registration
gdpr_questionnaire boolean - false Enable GDPR questionnaire
risk_scoring boolean - false Enable risk scoring
subscriptions boolean - false Enable subscriptions

Localization & Timezone

Field Type Range/Options Default Description
default_locale string it-IT, en-US, en-GB it-IT Default locale
default_timezone string IANA timezone Europe/Rome Default timezone
timestamp_format string - dd/MM/yyyy HH:mm Timestamp format

Export/Reporting

Field Type Range/Options Default Description
max_export_rows number 100-1000000 10000 Max export rows
default_export_filename_prefix string - conformo_export Export filename prefix
enable_csv_export boolean - true Enable CSV export
enable_pdf_export boolean - false Enable PDF export

Privacy/GDPR

Field Type Range/Options Default Description
enable_right_to_erasure boolean - true Enable right to erasure
enable_retention_enforcement boolean - true Enforce retention policy
auto_cleanup_enabled boolean - true Auto cleanup enabled
cleanup_schedule_day number 0-6 (0=Sunday) 0 Cleanup schedule day
cleanup_schedule_hour number 0-23 2 Cleanup schedule hour

Advanced/Operational

Field Type Range/Options Default Description
enable_rate_limiting boolean - true Enable rate limiting
rate_limit_window_minutes number 1-60 15 Rate limit window
rate_limit_max_requests number 10-10000 100 Max requests per window
enable_webhook_integrations boolean - false Enable webhooks
webhook_urls string[] - null Webhook URLs

Validation Rules

All updates are validated according to the following rules:

Numeric Fields

  • Must be within specified min/max ranges
  • Must be integers (no decimals)

Boolean Fields

  • Must be true or false

String Fields

  • from_email: Must be valid email format
  • environment: Must be one of: development, staging, production
  • default_locale: Must be one of: it-IT, en-US, en-GB
  • default_timezone: Should be valid IANA timezone (not strictly validated)

Array Fields

  • trusted_domains: Array of domain strings
  • webhook_urls: Array of URL strings

Audit Logging

All preference changes are logged in the admin_action_logs table with:

  • Admin user ID
  • Action type: SETTINGS_CHANGE
  • Resource type: admin_preferences
  • Timestamp
  • IP address
  • User agent
  • Metadata including list of changed fields

Error Messages (Italian)

All error messages are returned in Italian:

  • "Non autenticato" - Not authenticated
  • "Accesso negato" - Access denied (not admin)
  • "Nessun campo da aggiornare" - No fields to update
  • "Preferenze non trovate" - Preferences not found
  • "Session timeout deve essere tra 5 e 43200 minuti" - Session timeout validation
  • "Lunghezza minima password deve essere tra 8 e 128 caratteri" - Password length validation
  • "Formato email non valido" - Invalid email format
  • And more specific validation messages…

Usage Examples

TypeScript/JavaScript (Frontend)

import axios from 'axios';

// Get preferences
const getPreferences = async (accessToken: string) => {
  const response = await axios.get('/api/admin/preferences', {
    headers: { Authorization: `Bearer ${accessToken}` }
  });
  return response.data;
};

// Update preferences
const updatePreferences = async (accessToken: string, updates: any) => {
  const response = await axios.put('/api/admin/preferences', updates, {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  });
  return response.data;
};

// Example usage
const preferences = await getPreferences(token);
console.log('Current password min length:', preferences.password_min_length);

const result = await updatePreferences(token, {
  password_min_length: 14,
  admin_2fa_enforcement: true
});
console.log('Updated:', result.message);

cURL

# Get preferences
curl -X GET https://conformo.ai/api/admin/preferences \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Update preferences
curl -X PUT https://conformo.ai/api/admin/preferences \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password_min_length": 14,
    "admin_2fa_enforcement": true,
    "max_export_rows": 50000
  }'

Database Schema

The preferences are stored in a single-row table using the singleton pattern:

CREATE TABLE admin_preferences (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  -- All preference fields...
  updated_by UUID REFERENCES users(id),
  updated_at TIMESTAMP DEFAULT NOW(),
  created_at TIMESTAMP DEFAULT NOW()
);

-- Single row with fixed UUID
INSERT INTO admin_preferences (id)
VALUES ('00000000-0000-0000-0000-000000000001');

Security Considerations

  1. Admin-Only Access: Only users with role = 'admin' can access these endpoints
  2. Audit Trail: All changes are logged for compliance
  3. Validation: All inputs are validated before saving
  4. Rate Limiting: Subject to general API rate limits
  5. HTTPS Required: Always use HTTPS in production
  6. Token Expiry: Access tokens expire after 15 minutes

Integration with Other Systems

The preferences system integrates with:

  • Feature Flags (shared/featureFlags.ts): Feature flag preferences can override code defaults
  • Authentication System: Password and session policies affect login behavior
  • Audit Logger (adminLogger.ts): All changes are logged
  • Log Retention (log_retention_policy.sql): Retention settings affect cleanup schedule
  • Email Service: FROM_EMAIL setting affects outgoing emails

Best Practices

  1. Initial Setup: Run the migration SQL to create the table before first use
  2. Testing: Always test preference changes in staging before production
  3. Backup: Take database backup before major preference changes
  4. Monitoring: Monitor audit logs for unexpected preference changes
  5. Documentation: Document any custom preferences or non-standard values
  6. Validation: Use the UI (Admin Preferences page) which provides validation feedback

Migration Guide

To add the admin preferences system to an existing deployment:

  1. Run the migration SQL: 
    psql -d your_database < backend/db/migrations/admin_preferences.sql

  2. Deploy the backend with new API endpoints

  3. Deploy the frontend with Admin Preferences UI

  4. Access via Admin Dashboard → Preferenze tab

  5. Configure initial preferences according to your needs

Support

For issues or questions:

  • GitHub Issues: https://github.com/GrewingM/conformo/issues
  • Documentation: /docs/ADMIN_PREFERENCES.md
  • Admin Dashboard Guide: /docs/ADMIN_DASHBOARD.md