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",
    "auth": {
      "registration": true,
      "emailPassword": true,
      "magicLink": false,
      "passkey": true,
      "twoFactor": true,
      "socialProviders": ["google", "github", "discord"]
    }
  }
}

The auth block lets clients discover which login methods are actually enabled (and which social providers are credentialed) without hardcoding assumptions. See Discovering Enabled Auth Methods for the full field reference.

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",
    "session_limits": { "web": -1, "mobile": -1 },
    "web_session_limit": -1,
    "mobile_session_limit": -1
  }
}

The public GET /settings response only ever includes the default portion of session_limits (shown above as the flattened { "web": ..., "mobile": ... } object), plus the derived legacy hint keys web_session_limit and mobile_session_limit computed from it for older clients. Role IDs, per-role limits, and per-user overrides are never exposed on this public endpoint — only authenticated admin requests can see the full session_limits.roles map.

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",
  "session_limits": {
    "default": { "web": 5, "mobile": 3 },
    "roles": {
      "sales-role-uuid": { "web": 8, "mobile": 3 }
    }
  }
}

Success Response

{
  "data": {
    "id": "settings-uuid",
    "project_name": "New App Name",
    "project_color": "#ff5722",
    "timezone": "America/New_York",
    "session_limits": {
      "default": { "web": 5, "mobile": 3 },
      "roles": {
        "sales-role-uuid": { "web": 8, "mobile": 3 }
      }
    },
    "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",
    "session_limits": { "default": { "web": 5, "mobile": 3 } }
  }'

A tenant's session_limits fully replaces the global session_limits when both exist — values are not deep merged. See the Session Limits Feature guide for the full resolution order and per-user override behavior.

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
session_limits	JSON, nullable	`{ "default": { "web": n, "mobile": n }, "roles": { "<role-id>": { "web": n, "mobile": n } } }`. `-1`=unlimited, `0`=disabled. Tenant value fully replaces the global value (no merge). See Session Limits Feature.	null

The public GET /settings endpoint only exposes session_limits.default (plus derived web_session_limit / mobile_session_limit hint keys for older clients) — never the roles map. session_limits is also present on the baasix_User record as a nullable JSON field for per-user overrides; null/absent means inherit from the role/default resolution.

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
BODY_SIZE_LIMIT	Max JSON request body size	20mb
COUNT_BY_DEFAULT	Compute `totalCount` on list reads	true

Security Hardening

These default to secure (on) — set to false only to relax a protection. SQL-injection protection (identifier allowlisting and JSONB numeric-operand validation) is always on and has no toggle.

Variable	Description	Default
PROTECT_PRIVILEGE_FIELDS	Privilege fields (`role_Id`, `tenant_Id`, `userCreated_Id`, `userUpdated_Id`, `emailVerified`, hidden fields) are excluded from a `fields:[""]` grant and must be named explicitly. Admins are exempt. Tri-state: `true` (default) — `password` denied to non-admins even when explicitly granted; `allow-password` — a non-admin role may set `password` when explicitly* granted (`fields:["*","password"]`, e.g. delegated password reset); `false` — protection off. Passwords are always auto-hashed.	true
PROTECT_IS_PUBLIC_FIELD	Make baasix_File `isPublic` (which serves a file publicly, cross-tenant, no auth) opt-in: writable only when named explicitly in a permission, not via a broad `*` grant. Default off (backward compatible).	false
EXPOSE_ERROR_DETAILS	Include raw DB/internal error text in responses. Default off in production (raw PG messages leak schema and are an injection oracle); on otherwise. Production returns a generic message + correlation id.	(prod: false)
STORAGE_PATH_CONFINEMENT	Confine all local-disk file operations within the storage root (blocks path traversal). Null bytes are always rejected regardless.	true
STORAGE_FOLDER_STRUCTURE	Organize stored files into a per-tenant / per-user / system folder structure (`tenants/{t}/users/{u}/`, `tenants/{t}/system/`, `users/{u}/`, `system/`). Default off (flat). Existing files are unaffected (legacy flat layout). Migrate existing files via the admin endpoint `POST /files/migrate-storage-structure` (supports `?dryRun=true`; crash-safe, idempotent, resumable).	false
ASSET_XSS_PROTECTION	Force executable upload types (`text/html`, `image/svg+xml`, `*/javascript`, xml) to download instead of rendering inline on `/assets`.	true
ASSET_NOSNIFF	Send `X-Content-Type-Options: nosniff` on asset responses.	true
STRICT_TENANT_ISOLATION	(Multi-tenant only) Restrict the `isTenantSpecific:false` tenant-scoping bypass to the administrator role; a non-admin role marked `isTenantSpecific:false` is still tenant-scoped. Set `false` for legacy behavior.	true
OAUTH_ALLOW_UNVERIFIED_LINK	Auto-link OAuth login to an existing account when the provider's email is unverified. Default off (secure — only link verified emails; prevents takeover).	false
OAUTH_ALLOW_DIRECT_IDTOKEN	Allow client-supplied direct ID-token sign-in (`POST /auth/social/signin` with `idToken`). Default off; requires JWKS verification (Google/Apple). Redirect flow unaffected.	false
OAUTH_STATE_COOKIE_BINDING	Bind OAuth `state` to the browser via httpOnly cookie (CSRF). Default off (cross-site/SPA/Apple callbacks may not carry the cookie).	false
SSRF_ALLOW_PRIVATE_URL_FETCH	Allow server-side URL fetches (upload-from-URL, workflow HTTP node) to reach private/loopback/metadata addresses. Default off (secure — blocked, resolved-IP + per-redirect checked).	false
URL_FETCH_TIMEOUT_MS	Response timeout (ms) per request/redirect hop for upload-from-URL (time-to-first-response, not total download time; total size is capped by `MAX_UPLOAD_FILE_SIZE`).	15000
ASSET_MAX_DIMENSION	Max output width/height (px) for on-the-fly image transforms; larger requests are clamped (DoS guard).	5000
ASSET_MAX_INPUT_PIXELS	Max input pixels the image decoder accepts (sharp `limitInputPixels`; decompression-bomb defense).	100000000

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	-
DATABASE_POSTGIS	Enable PostGIS extension	false
DATABASE_VECTOR	Enable pgvector extension	false

System Cache

System cache stores permissions, roles, and settings. Always enabled (defaults to memory).

Variable	Description	Default
SYSTEM_CACHE_ADAPTER	Cache backend (memory/redis/upstash)	memory
SYSTEM_CACHE_REDIS_URL	Redis connection URL	-
SYSTEM_CACHE_TTL	Cache TTL in seconds	30
SYSTEM_CACHE_SYNC_INTERVAL	L1↔L2 sync interval in seconds (Redis only)	5
SYSTEM_CACHE_SIZE_GB	In-memory cache size (GB)	1.0

Data Cache (Query Results)

Variable	Description	Default
DATA_CACHE_ENABLED	Enable/disable query caching	true
DATA_CACHE_ADAPTER	Cache backend (memory/redis/upstash)	memory
DATA_CACHE_REDIS_URL	Redis connection URL	-
DATA_CACHE_TTL	Cache TTL in seconds	300
DATA_CACHE_STRATEGY	Cache strategy (explicit/all)	explicit
DATA_CACHE_SIZE_GB	In-memory cache size (GB)	1.0

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 list of trusted frontend app origins — used for CORS and to validate OAuth `redirect_url` / callback targets	-
BASE_URL	Your API's own public origin, used to build the OAuth callback `redirect_uri` (`{BASE_URL}/auth/callback/{provider}`). Read at startup but not validated — if unset, OAuth callbacks silently build a relative (host-less) URL. Required whenever any social provider is enabled.	-
PUBLIC_REGISTRATION	Allow public self-serve signup via `POST /auth/register`. When `false`, that endpoint returns 403 `REGISTRATION_DISABLED` unless the request carries a valid invite token — invitations always continue to work.	true

Authentication Services

Variable	Description	Default
AUTH_SERVICES_ENABLED	Comma-separated list of enabled auth methods (uppercase): `LOCAL`, `PASSKEY`, `TWOFACTOR`, and/or any of the 35 provider ids (e.g. `GOOGLE`, `GITHUB`, `DISCORD`, ...). See the full 35-provider list in the SSO guide.	LOCAL
`<PROVIDERID>`_CLIENT_ID	OAuth client id for a given provider (e.g. `GOOGLE_CLIENT_ID`). A provider only activates when it's both listed in `AUTH_SERVICES_ENABLED` and fully credentialed.	-
`<PROVIDERID>`_CLIENT_SECRET	OAuth client secret for a given provider (e.g. `GOOGLE_CLIENT_SECRET`)	-
APPLE_TEAM_ID / APPLE_KEY_ID / APPLE_PRIVATE_KEY	Extra credentials required by Apple Sign In, alongside `APPLE_CLIENT_ID`/`APPLE_CLIENT_SECRET`	-
MICROSOFT_TENANT_ID	Tenant scoping for Microsoft (Entra ID) sign-in	common
TIKTOK_CLIENT_KEY	Extra key required by TikTok, alongside `TIKTOK_CLIENT_ID`/`TIKTOK_CLIENT_SECRET`	-
COGNITO_DOMAIN / COGNITO_REGION	Required for AWS Cognito, alongside `COGNITO_CLIENT_ID`/`COGNITO_CLIENT_SECRET`	-
WECHAT_CLIENT_ID / WECHAT_CLIENT_SECRET	Repurposed for WeChat: `WECHAT_CLIENT_ID` holds the WeChat appid, `WECHAT_CLIENT_SECRET` holds the WeChat secret	-
PASSKEY_RP_ID	WebAuthn Relying Party ID — must match your app's domain (e.g. `example.com`). Required for passkeys to activate.	-
PASSKEY_RP_NAME	WebAuthn Relying Party display name shown in the browser's passkey prompt. Required for passkeys to activate.	-
PASSKEY_ORIGIN	Comma-separated list of allowed origins (scheme+host+port) for WebAuthn. Required for passkeys to activate.	-

See the SSO & Social Authentication guide, Passkeys guide, and Two-Factor Authentication guide for the complete configuration walkthrough and API reference for each auth method.

Rate Limiting

Variable	Description	Default
RATE_LIMIT	Max requests per window	100
RATE_LIMIT_INTERVAL	Rate limit window (ms)	5000
AUTH_RATE_LIMIT	Brute-force limit for login/magic-link/password-reset, counted per (IP + email) pair (each account has its own budget per IP). Protects targeted brute-force; does not cap an IP's total attempts across many accounts (use a WAF/edge limit for password spraying).	10
AUTH_RATE_LIMIT_INTERVAL	Window (ms) for the auth brute-force limiter	900000
AUTH_RATE_LIMIT_DISABLED	Disable the auth brute-force limiter (auto-disabled in TEST_MODE)	false
RATE_LIMIT_BY_USER	Rate limit by user ID instead of IP (for authenticated users)	false

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
MAX_UPLOAD_FILE_SIZE	Maximum file upload size in MB (default: 50)
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
WORKFLOWS_ENABLED	Master switch for the workflow subsystem. Default on. Set false to fully disable workflows (no item-event hooks → no per-request trigger overhead, no scheduled runs, /workflows/* → 404, no code execution). Recommended off if you don't use workflows.	true
SOCKET_ENABLED	Enable Socket.IO	false
REALTIME_ROW_LEVEL_SCOPING	Per-recipient row-level scoping for realtime broadcasts (A12): deliver a change only to subscribers whose read permission allows the row. Default off (fast room broadcast; subscribers may see other rows in their tenant). Adds per-change cost scaling with distinct subscriber roles.	false
SOCKET_PATH	Socket.IO connection path	/realtime
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
TASK_CONCURRENCY	Max concurrent tasks per instance	1
TASK_STALL_TIMEOUT	Seconds before a Running task is considered stalled	300
TASK_REDIS_ENABLED	Enable Redis for distributed task locking	false
TASK_REDIS_URL	Redis URL for task service distributed locking	-

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