Settings Routes

Overview
Get Project Info
Get Settings
Get Settings by App URL
Update Settings
Get Email Branding
Test Email Configuration
Reload Settings Cache
Delete Tenant Settings
Database Settings Reference
Environment Variables Reference

Overview

The Settings API provides configuration management for the BAASIX application. Settings can be stored in the database (for runtime configuration) or set via environment variables (for server configuration).

Base URLs: / and /settings

Get Project Info

Get basic project information. This is a public endpoint.

URL: / or POST /
Method: GET or POST
Auth required: No (Public endpoint)

Success Response

{
  "data": {
    "project_name": "My Application",
    "title": "My App",
    "project_color": "#007bff",
    "secondary_color": "#6c757d",
    "description": "Application description",
    "project_url": "https://api.myapp.com",
    "app_url": "https://myapp.com"
  }
}

Example Request

curl -X GET "http://localhost:3000/"

Get Settings

Retrieve application settings. Returns global or tenant-specific settings.

URL: /settings
Method: GET
Auth required: No (Public endpoint, but some fields may require admin)

Query Parameters

Parameter	Type	Description
tenant_id	string	Get settings for specific tenant (optional)

Success Response

{
  "data": {
    "project_name": "My Application",
    "title": "My App Title",
    "project_color": "#007bff",
    "secondary_color": "#6c757d",
    "description": "Application description",
    "keywords": "baasix, backend, api",
    "project_url": "https://api.myapp.com",
    "app_url": "https://myapp.com",
    "timezone": "UTC",
    "language": "en",
    "date_format": "YYYY-MM-DD",
    "currency": "USD",
    "from_email_name": "My App",
    "email_signature": "Best regards,\nMy App Team",
    "mobile_session_limit": -1,
    "web_session_limit": -1
  }
}

Example Request

# Get global settings
curl -X GET "http://localhost:3000/settings"

# Get tenant-specific settings
curl -X GET "http://localhost:3000/settings?tenant_id=tenant-123"

Get Settings by App URL

Retrieve settings for a specific application URL. Useful for multi-tenant frontends.

URL: /settings/by-app-url
Method: GET
Auth required: No (Public endpoint)

Query Parameters

Parameter	Type	Required	Description
app_url	string	Yes	The application URL to match

Success Response

{
  "data": {
    "project_name": "Tenant App",
    "title": "Tenant Application",
    "project_color": "#ff5722",
    "app_url": "https://tenant.myapp.com",
    "tenant_Id": "tenant-uuid"
  }
}

Example Request

curl -X GET "http://localhost:3000/settings/by-app-url?app_url=https://tenant.myapp.com"

Update Settings

Update application settings. Admin only.

URL: /settings
Method: PATCH
Auth required: Yes (Admin permissions required)

Request Body

Settings are updated as key-value pairs directly:

{
  "project_name": "New App Name",
  "project_color": "#ff5722",
  "timezone": "America/New_York",
  "mobile_session_limit": 3,
  "web_session_limit": 5
}

Success Response

{
  "data": {
    "id": "settings-uuid",
    "project_name": "New App Name",
    "project_color": "#ff5722",
    "timezone": "America/New_York",
    "mobile_session_limit": 3,
    "web_session_limit": 5,
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Example Request

curl -X PATCH http://localhost:3000/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "project_name": "My Updated App",
    "timezone": "America/New_York",
    "mobile_session_limit": 3
  }'

Get Email Branding

Get email branding information for a tenant (used for email templates).

URL: /settings/branding
Method: GET
Auth required: No (but tenant_id is required)

Query Parameters

Parameter	Type	Required	Description
tenant_id	string	Yes	The tenant ID

Success Response

{
  "data": {
    "project_name": "Tenant App",
    "project_color": "#007bff",
    "email_icon_Id": "file-uuid",
    "email_signature": "Best regards,\nTenant Team"
  }
}

Example Request

curl -X GET "http://localhost:3000/settings/branding?tenant_id=tenant-123"

Test Email Configuration

Test the email configuration by sending a test email. Admin only.

URL: /settings/test-email
Method: POST
Auth required: Yes (Admin permissions required)

Request Body

Parameter	Type	Required	Description
to	string	Yes	Email address to send test to

Example Request

curl -X POST http://localhost:3000/settings/test-email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"to": "test@example.com"}'

Reload Settings Cache

Force reload of settings from database into cache. Admin only.

URL: /settings/reload
Method: POST
Auth required: Yes (Admin permissions required)

Example Request

curl -X POST http://localhost:3000/settings/reload \
  -H "Authorization: Bearer <admin-token>"

Delete Tenant Settings

Delete settings for a specific tenant. Admin only.

URL: /settings/tenant
Method: DELETE
Auth required: Yes (Admin permissions required)

Query Parameters

Parameter	Type	Required	Description
tenant_id	string	Yes	Tenant ID to delete

Example Request

curl -X DELETE "http://localhost:3000/settings/tenant?tenant_id=tenant-123" \
  -H "Authorization: Bearer <admin-token>"

Database Settings Reference

These settings are stored in the baasix_Settings table and can be updated via the API:

Branding & Identity

Setting Key	Type	Description	Default
project_name	string	Project/application name	-
title	string	Application title for display	-
project_color	string	Primary brand color (hex)	-
secondary_color	string	Secondary brand color (hex)	-
description	string	Application description (SEO)	-
keywords	string	SEO keywords	-
project_url	string	API/Backend URL	-
app_url	string	Frontend application URL	-

Logo & Icon Assets (File References)

Setting Key	Type	Description
project_logo_light_Id	UUID	Light theme logo file ID
project_logo_dark_Id	UUID	Dark theme logo file ID
project_logo_full_Id	UUID	Full logo with text file ID
project_logo_transparent_Id	UUID	Transparent logo file ID
project_favicon_Id	UUID	Favicon file ID
project_icon_Id	UUID	App icon file ID
email_icon_Id	UUID	Email template icon file ID

Email Configuration (Database)

Setting Key	Type	Description	Default
from_email_name	string	From address display name	-
email_signature	string	Email signature template	-
smtp_enabled	boolean	Enable SMTP	false
smtp_host	string	SMTP server hostname	-
smtp_port	number	SMTP server port	587
smtp_secure	boolean	Use TLS/SSL	false
smtp_user	string	SMTP username	-
smtp_pass	string	SMTP password	-
smtp_from_address	string	SMTP from email address	-

Localization

Setting Key	Type	Description	Default
timezone	string	Default timezone	"UTC"
language	string	Default language	"en"
date_format	string	Date display format	"YYYY-MM-DD"
currency	string	Default currency	"USD"

Session Management

Setting Key	Type	Description	Default
mobile_session_limit	number	Max mobile sessions per user (-1=unlimited)	-1
web_session_limit	number	Max web sessions per user (-1=unlimited)	-1
session_limit_roles	JSON	Array of role IDs to apply limits to	[]

Extensibility

Setting Key	Type	Description
metadata	JSON	Custom metadata storage
modules	JSON	Module configuration

Environment Variables Reference

These settings are configured via environment variables at server startup:

Core Server

Variable	Description	Default
PORT	Server port	8055
SECRET_KEY	JWT signing key (required)	-
NODE_ENV	Environment (production/dev)	development

Database

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	-
DATABASE_POOL_MAX	Max connection pool size	20
DATABASE_POOL_IDLE	Idle timeout (ms)	10000
DATABASE_POOL_ACQUIRE	Acquire timeout (ms)	30000
DATABASE_LOGGING	Enable SQL logging	false
DATABASE_SSL_CERTIFICATE	Path to SSL certificate	-
DATABASE_READ_REPLICA_ENABLED	Enable read replicas	false
DATABASE_READ_REPLICA_URLS	Comma-separated replica URLs	-

Cache (Redis)

Variable	Description	Default
CACHE_ADAPTER	Cache backend (memory/redis/upstash)	memory
CACHE_REDIS_URL	Redis connection URL	-
CACHE_TTL	Cache TTL in seconds	30
CACHE_SIZE_GB	In-memory cache size (GB)	1.0
CACHE_ENABLED	Enable/disable caching	true

CORS & Authentication

Variable	Description	Default
AUTH_CORS_ALLOWED_ORIGINS	Comma-separated allowed CORS origins	-
AUTH_CORS_ALLOW_ANY_PORT	Allow any port for CORS matching	true
AUTH_CORS_CREDENTIALS	Include credentials in CORS	true
AUTH_APP_URL	Comma-separated allowed app URLs	-

Rate Limiting

Variable	Description	Default
RATE_LIMIT	Max requests per window	100
RATE_LIMIT_INTERVAL	Rate limit window (ms)	5000

Multi-Tenancy

Variable	Description	Default
MULTI_TENANT	Enable multi-tenant mode	false

Mail Service

Variable	Description
MAIL_SENDERS_ENABLED	Comma-separated list of mail senders
MAIL_DEFAULT_SENDER	Default sender name
`<SENDER>`_SMTP_HOST	SMTP host for sender
`<SENDER>`_SMTP_PORT	SMTP port for sender
`<SENDER>`_SMTP_SECURE	TLS/SSL for sender (true/false)
`<SENDER>`_SMTP_USER	SMTP username for sender
`<SENDER>`_SMTP_PASS	SMTP password for sender
`<SENDER>`_FROM_ADDRESS	From email address for sender

File Storage

Variable	Description
STORAGE_SERVICES_ENABLED	Comma-separated list of storage services
STORAGE_DEFAULT_SERVICE	Default storage service
STORAGE_TEMP_PATH	Temporary file storage path
`<SERVICE>`_STORAGE_DRIVER	Storage driver (LOCAL or S3)
`<SERVICE>`_STORAGE_PATH	Local storage path
`<SERVICE>`_STORAGE_ACCESS_KEY_ID	S3 access key
`<SERVICE>`_STORAGE_SECRET_ACCESS_KEY	S3 secret key
`<SERVICE>`_STORAGE_REGION	S3 region
`<SERVICE>`_STORAGE_BUCKET	S3 bucket name
`<SERVICE>`_STORAGE_ENDPOINT	S3 endpoint URL

Real-time (Socket.IO)

Variable	Description	Default
SOCKET_ENABLED	Enable Socket.IO	false
SOCKET_PATH	Socket.IO connection path	/socket
SOCKET_CORS_ENABLED_ORIGINS	CORS origins for WebSocket	-
SOCKET_REDIS_ENABLED	Use Redis for Socket.IO clustering	false
SOCKET_REDIS_URL	Redis URL for Socket.IO adapter	-

Task Management

Variable	Description	Default
TASK_SERVICE_ENABLED	Enable background task service	false
TASK_LIST_REFRESH_INTERVAL	Task cache refresh interval (sec)	600
TASK_SHUTDOWN_WAIT_TIME	Wait time for tasks on shutdown (sec)	30

Error Responses

Common Error Codes

Code	Message	Description
400	Invalid settings data	Malformed settings object
401	Unauthorized	Authentication required
403	Forbidden	Admin permissions required
404	Settings not found	No settings for given tenant
500	Settings update failed	Server error during update

Core Configuration

Deployment Guide - Production deployment and environment setup
Additional Features - Email templates, storage, caching

Authentication & Sessions

Authentication Routes - User authentication
Session Limits Feature - Session limit configuration

Multi-tenant

Multi-tenant Guide - Tenant-specific settings

Real-time & Tasks

Socket.IO Integration - WebSocket configuration
TasksService Documentation - Background task configuration

API Reference

API Routes Reference - Complete endpoint listing

← Back to Documentation Home

On this page