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
PROJECT_NAME	Project display name — used as the JWT issuer and in email templates	Baasix

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. `true` \| `false`. Password writes are a separate toggle (`ALLOW_PASSWORD_WRITES`). Deprecated: the old value `allow-password` still works and is equivalent to `true` + `ALLOW_PASSWORD_WRITES=true`.	true
ALLOW_PASSWORD_WRITES	Let a non-admin role set `password` via the data API when it is explicitly granted (`fields:["*","password"]`, e.g. delegated password reset). Default off — `password` is never client-writable via the data API (admins exempt; use the auth flow instead). Writes are always auto-hashed. Enabling this is surfaced in the startup security-posture banner.	false
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
SCHEMAS_PUBLIC	Allow unauthenticated reads of collection schemas via `GET /schemas`. Default on (backward compatible); set `false` in production so schema metadata requires a permission.	true
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_POOL_EVICT	Pool connection max-lifetime base value (ms)	1000
DATABASE_MAX_RETRY	Startup connection retry attempts	3
DATABASE_RETRY_INTERVAL	Delay between startup connection retries (ms)	5000
DATABASE_SSL_REJECT_UNAUTHORIZED	Reject self-signed/unverifiable SSL certificates	false
TRANSACTION_TIMEOUT_MS	Max transaction duration before forced rollback (ms)	60000
DATABASE_READ_REPLICA_ENABLED	Enable read replicas	false
DATABASE_READ_REPLICA_URLS	Comma-separated replica URLs	-
DATABASE_READ_REPLICA_POOL_MAX	Replica max pool size	20
DATABASE_READ_REPLICA_POOL_IDLE	Replica idle timeout (ms)	10000
DATABASE_READ_REPLICA_POOL_ACQUIRE	Replica acquire timeout (ms)	30000
DATABASE_READ_REPLICA_POOL_EVICT	Replica connection max-lifetime base value (ms)	1000
DATABASE_POSTGIS	Enable PostGIS extension	false
DATABASE_VECTOR	Enable pgvector extension	false

Migrations

Variable	Description	Default
MIGRATIONS_AUTO_RUN	Run pending migrations automatically at startup. When `false` (default), startup migrations are a no-op — run them via the CLI instead.	false
MIGRATIONS_DIR	Directory containing migration files	`./migrations`
MIGRATIONS_UPGRADE_BASELINE	Baasix version to baseline upgrade migrations from (advanced; normally auto-detected)	current version

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
UPSTASH_REDIS_REST_URL	Upstash REST URL — required when either cache uses the `upstash` adapter	-
UPSTASH_REDIS_REST_TOKEN	Upstash REST token — required when either cache uses the `upstash` adapter	-

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
ACCESS_TOKEN_EXPIRES_IN	Access-token / session lifetime in seconds	604800 (7 days)
AUTH_COOKIE_DOMAIN	`Domain` attribute for the auth cookie in cookie authMode (set to share the session across subdomains)	-
AUTH_COOKIE_SAME_SITE	`SameSite` attribute for the auth cookie in cookie authMode	strict (prod) / lax (dev)
DISABLE_SESSION_CLEANUP	Disable the periodic cleanup job that deletes expired sessions	false

Registration & Email Verification

Variable	Description	Default
REQUIRE_EMAIL_VERIFICATION	Require email verification before credential login. Registration then returns `requiresEmailVerification: true` with no token, auto-sends the verification email, and login returns 403 until the user opens `{link}/auth/verify-email/{token}`. A new email can be requested (unauthenticated) via `POST /auth/email/verify/resend`. Requires a configured mail sender.	false
DEFAULT_ROLE_REGISTERED	Role name assigned to self-registered users	user
ALLOWED_ROLES_MULTI_TENANT	Comma-separated role names a registrant may request via `roleName` in multi-tenant mode (empty = none)	-
SEND_WELCOME_EMAIL	Send the `welcome` template email after successful signup	false
WELCOME_EMAIL_SUBJECT	Override the welcome email's subject line	template subject
EMAIL_VERIFICATION_RESEND_COOLDOWN	Minimum seconds between verification emails per address (also counts registration's auto-send; `0` disables). Complements the per-IP auth rate limiter — stops a distributed caller from flooding one inbox.	60

With REQUIRE_EMAIL_VERIFICATION=true, magic-link login also verifies the address (receiving the link proves mailbox ownership), and OAuth sign-ins inherit the provider's verified status. The seeded admin@baasix.com account is created already-verified, so a fresh install can't lock itself out. See the Email Verification section of the Authentication guide.

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

A configured sender is required for verification, magic-link, invitation, password-reset, and welcome emails. Each name listed in MAIL_SENDERS_ENABLED is a prefix for its SMTP variables; a sender missing any of host/port/user/pass/from is skipped at startup.

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
ASSET_TEMP_DIR	Working directory for on-the-fly asset transforms (default: `./asset-temp`)
ASSET_PROXY_ENABLED	Stream S3 assets through the API instead of redirecting to a signed URL (default: false)
ASSET_SECURE_PROXY_URLS	Comma-separated content types (`video`, `audio`, `image`, or full types) that additionally require an authenticated request with a custom header — anti-hotlinking for proxied S3 assets
SHARED_ASSET_ACCESS_MODE	(Multi-tenant) Expose selected tenants' files across tenants: `public` or `authenticated` (default: off)
SHARED_ASSET_TENANT_IDS	Comma-separated tenant IDs whose files are shared under `SHARED_ASSET_ACCESS_MODE`

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	-
SOCKET_REDIS_KEY	Key prefix for the Socket.IO Redis adapter	socket.io
REALTIME_WAL_CONSUMER_ENABLED	Consume PostgreSQL WAL (logical replication) for realtime change capture when available. Set `false` to disable explicitly.	true

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	-

Logging & Log Cleanup

Variable	Description	Default
LOG_LEVEL	Log verbosity (`trace`/`debug`/`info`/`warn`/`error`)	info
LOG_WARN_STACK	Include stack traces on `warn`-level logs	false
AUDIT_LOG_CLEANUP_ENABLED	Periodically delete old audit-log rows	false
AUDIT_LOG_RETENTION_DAYS	Audit-log retention when cleanup is enabled (days)	90
EMAIL_LOG_CLEANUP_ENABLED	Periodically delete old email-log rows	false
EMAIL_LOG_RETENTION_DAYS	Email-log retention when cleanup is enabled (days)	30

MCP & OpenAPI

Variable	Description	Default
MCP_ENABLED	Expose the MCP endpoint for AI agents	false
MCP_PATH	URL path of the MCP endpoint	/mcp
MCP_ENABLED_ACTIONS	Comma-separated MCP tool groups to register: `all`, `read`, `create`, `update`, `delete`	all
OPENAPI_ENABLED	Serve the generated OpenAPI spec (`false`/`0` disables)	true
OPENAPI_INCLUDE_AUTH	Include auth endpoints in the spec	false
OPENAPI_INCLUDE_SCHEMA	Include schema-management endpoints in the spec	false
OPENAPI_INCLUDE_PERMISSIONS	Include permission endpoints in the spec	false
OPENAPI_INCLUDE_SETTINGS	Include settings endpoints in the spec	false
OPENAPI_INCLUDE_NOTIFICATIONS	Include notification endpoints in the spec	false
OPENAPI_INCLUDE_MULTI_TENANT	Include multi-tenant endpoints in the spec	false
OPENAPI_INCLUDE_UTILS	Include utility endpoints in the spec	false

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