Get Settings
Overview
Fetch the authenticated tenant's Platform settings document — feature toggles, group defaults, message timers, attachment rules, and the plan ceilings in limits.
Use this to hydrate the Platform → Settings screen before the client edits values with Update Settings. Chat apps that only need the resolved runtime config should prefer Effective Settings instead.
When to use this endpoint?
Use Get Settings when:
- Opening Platform → Settings to show current toggles and limits.
- Loading the latest document before a PATCH Update so the form is not stale.
- Displaying plan ceilings from
limitsnext to editablesettingscontrols (for example max file size or group size). - Confirming call / push / block / group-creation flags after a save.
Part of the client Platform Settings module. Requires a client Access Token with tenant admin privileges. Not the chat SDK effective settings endpoint.
Response Data
The data object is the full settings document. Treat limits as read-only ceilings; settingsholds the tenant's chosen values (must not exceed those ceilings).
Top-level fields
limits
settings - feature toggles & chosen limits
settings.calls
settings.groupPolicy
Seeds default permissions for new groups. Flags listed in locked stay pinned to their default and cannot be overridden per conversation by group admins.
settings.messageTimers
{baseUrl}/api/{apiVersion}/settings- Authentication
- Required (Bearer token)
- Tenant-scoped
- Yes (tenant DB - requires x-client-id)
Request Headers
Success Response (HTTP 200 OK)
On success, the API returns the full settings document, including limits and settings.
{ "success": true, "message": "Settings fetched successfully", "data": { "_id": "6a57...739c", "clientId": "6a57...f0c0", "__v": 0, "createdAt": "2026-07-15T04:45:28.064Z", "limits": { "attachments": { "enabled": true, "maxFileSizeMB": 25, "maxAttachmentsPerMessage": 10, "allowedMimeTypes": ["*"] }, "maxAdminsPerGroup": 5, "maxParticipantsPerGroup": 256, "maxPinnedMessagesPerConversation": 10, "groupCreationEnabled": true }, "metadata": {}, "settings": { "calls": { "enabled": false, "videoSdkToken": "" }, "groupPolicy": { "defaults": { "onlyAdminCanSendMessage": false, "onlyAdminCanEditInfo": false, "senderCanEditMessage": true, "allowMemberAdd": false, "allowMemberRemove": false, "moderationEnabled": false }, "locked": [] }, "messageTimers": { "dmEditMinutes": 5, "dmDeleteMinutes": 10, "groupEditMinutes": 10, "groupDeleteMinutes": 10 }, "attachments": { "enabled": true, "maxFileSizeMB": 25, "maxAttachmentsPerMessage": 10, "allowedMimeTypes": ["*"] }, "pushNotificationEnabled": true, "videoCallEnabled": true, "audioCallEnabled": true, "blockUsersEnabled": true, "canvasEnabled": true, "whiteboardEnabled": true, "maxAdminsPerGroup": 5, "maxParticipantsPerGroup": 256, "maxPinnedMessagesPerConversation": 10, "groupCreationEnabled": true }, "updatedAt": "2026-07-15T04:45:28.064Z" }, "error": null}Common Errors
Fetch fails when the token is missing/invalid or the caller is not a tenant admin.
HTTP 401 Unauthorized - No token
{ "success": false, "message": "No token, authorization denied", "data": null, "error": "Unauthorized"}HTTP 403 Forbidden - Tenant admin required
{ "success": false, "message": "Access denied: tenant admin privileges required", "data": null, "error": null}Best Practices
- Bind form max values from
limitsso users cannot submit values the API will reject. - Refetch after every successful Update so
updatedAtand nested objects stay in sync. - Treat
videoSdkTokenas a secret — never log it or expose it in public URLs. - Explain
groupPolicy.lockedin the UI so admins know which defaults cannot be changed per group later. - For chat SDK clients that only enforce runtime rules, use Effective Settings instead of this admin document.
Settings loaded
Use data.settings to populate the Platform form and data.limits for ceilings, then call Update Settings to save changes.