Effective Settings

Overview

Fetch the tenant's resolved settings - the values your Platform UI or product logic should enforce at runtime after plan ceilings and admin configuration are applied.

Unlike Get Settings, this response is a flat effective object: no document id, no separate limits block, and no raw videoSdkToken. Use it to drive feature gates, attachment pickers, group defaults, and edit/delete windows.

When to use this endpoint?

Use Effective Settings when:

Hydrating runtime toggles (push, calls, block users, group creation) after login or app boot.
Checking whether calling is ready via calls.enabled and calls.configured without reading the secret token.
Applying groupPolicy defaults and locked flags when creating or constraining groups.
Enforcing message edit/delete windows from messageTimers.
Validating attachment size, MIME types, and count before upload.

Part of the client Platform Settings module. For editing tenant configuration (including storing a VideoSDK token), use Get Settings + Update Settings instead.

Effective vs Get Settings

Aspect	Get Settings	Effective Settings
Purpose	Admin document for Platform → Settings forms	Resolved values for runtime enforcement
Shape	`_id`, `clientId`, `limits`, `settings`	Flat feature object only (no wrapping `settings` key)
calls	`enabled` + `videoSdkToken`	`enabled` + `configured` (token never returned)
Write?	Pair with Update Settings (PATCH)	Read-only

Response Data

The data object is the effective configuration. Key groups:

Feature toggles & limits

Field	Description
pushNotificationEnabled	Whether push notifications are allowed for this tenant.
videoCallEnabled	Tenant video-call toggle (combine with `calls`).
audioCallEnabled	Tenant audio-call toggle (combine with `calls`).
blockUsersEnabled	Whether users may block other users.
canvasEnabled	Whether collaborative documents (Canvas) are available (platform ceiling AND tenant toggle).
whiteboardEnabled	Whether collaborative drawing boards (Whiteboard) are available (platform ceiling AND tenant toggle).
maxAdminsPerGroup	Effective max admins allowed per group.
maxParticipantsPerGroup	Effective max participants per group.
maxPinnedMessagesPerConversation	Effective max pinned messages per conversation.
groupCreationEnabled	Whether chat users may create groups.

calls

Field	Description
enabled	Master switch for the calling integration.
configured	`true` when a VideoSDK token has been saved (token itself is never returned here).

Treat calling as ready only when calls.enabled and calls.configured are both true, and the relevant videoCallEnabled / audioCallEnabled toggle is on.

groupPolicy / messageTimers / attachments

Same nested shapes as under settings on Get: groupPolicy.defaults + locked, edit/delete minutes, and attachment rules (enabled, maxFileSizeMB, allowedMimeTypes, maxAttachmentsPerMessage). See Get Settings → Response Data for flag-by-flag descriptions.

GET{baseUrl}/api/{apiVersion}/settings/effective

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges (Platform panel).
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

Success Response (HTTP 200 OK)

On success, the API returns the flattened effective settings object.

json

1{2  "success": true,3  "message": "Effective settings fetched successfully",4  "data": {5    "pushNotificationEnabled": true,6    "videoCallEnabled": false,7    "audioCallEnabled": true,8    "blockUsersEnabled": true,9    "canvasEnabled": true,10    "whiteboardEnabled": true,11    "calls": {12      "enabled": true,13      "configured": true14    },15    "groupPolicy": {16      "defaults": {17        "onlyAdminCanSendMessage": true,18        "onlyAdminCanEditInfo": false,19        "senderCanEditMessage": true,20        "allowMemberAdd": true,21        "allowMemberRemove": false,22        "moderationEnabled": false23      },24      "locked": [25        "onlyAdminCanSendMessage"26      ]27    },28    "messageTimers": {29      "dmEditMinutes": 15,30      "dmDeleteMinutes": 10,31      "groupEditMinutes": 10,32      "groupDeleteMinutes": 6033    },34    "attachments": {35      "enabled": true,36      "maxFileSizeMB": 10,37      "allowedMimeTypes": [38        "image/*",39        "application/pdf"40      ],41      "maxAttachmentsPerMessage": 1042    },43    "maxAdminsPerGroup": 5,44    "maxParticipantsPerGroup": 100,45    "maxPinnedMessagesPerConversation": 10,46    "groupCreationEnabled": true47  },48  "error": null49}

Common Errors

Fetch fails when the token is missing/invalid or the caller is not a tenant admin.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Settings.
500 Internal Server Error	An unexpected error occurred while fetching effective settings.

Best Practices

Prefer Effective for runtime gates; use Get/Update only when editing admin configuration.
Cache briefly after boot, then refetch after a successful Update so UI matches the server.
Never expect videoSdkToken here — use calls.configured instead.
Honor groupPolicy.locked so group admins cannot override pinned defaults.
Validate uploads against effective attachments before requesting presigned URLs.