zulip/api_docs/group-setting-values.md

Group-setting values

Settings defining permissions in Zulip are increasingly represented using user groups, which offer much more flexible configuration than the older roles system.

!!! warn ""

This API feature is under development, and currently only values that
correspond to a single named user group are permitted in
production environments, pending the web application UI supporting
displaying more complex values correctly.

In the API, these settings are represented using a group-setting value, which can take two forms:

• An integer user group ID, which can be either a named user group visible in the UI or a role-based system group.
• An object with fields direct_member_ids containing a list of integer user IDs and direct_subgroup_ids containing a list of integer group IDs. The setting's value is the union of the identified collection of users and groups.

Group-setting values in the object form function very much like a formal user group object, without requiring the naming and UI clutter overhead involved with creating a visible user group just to store the value of a single setting.

The server will canonicalize an object with empty direct_member_ids and with direct_subgroup_ids containing just the given group ID to the integer format.

System groups

The Zulip server maintains a collection of system groups that correspond to the users with a given role; this makes it convenient to store concepts like "all administrators" in a group-setting value. These use a special naming convention and can be recognized by the is_system_group property on their group object.

The following system groups are maintained by the Zulip server:

• role:internet: Everyone on the Internet has this permission; this is used to configure the public access option.
• role:everyone: All users, including guests.
• role:members: All users, excluding guests.
• role:fullmembers: All full members of the organization.
• role:moderators: All users with at least the moderator role.
• role:administrators: All users with at least the administrator role.
• role:owners: All users with the owner role.
• role:nobody: The formal empty group. Used in the API to represent disabling a feature.

Client UI for setting a permission is encouraged to display system groups using their description, rather than using their names, which are chosen to be unique and clear in the API.

System groups should generally not be displayed in UI for administering an organization's user groups, since they are not directly mutable.

Updating group-setting values

The Zulip API uses a special format for modifying an existing setting using a group-setting value.

A group-setting update is an object with a new field and an optional old field, each containing a group-setting value. The setting's value will be set to the membership expressed by the new field.

The old field expresses the client's understanding of the current value of the setting. If the old field is present and does not match the actual current value of the setting, then the request will fail with error code EXPECTATION_MISMATCH and no changes will be applied.

When a user edits the setting in a UI, the resulting API request should generally always include the old field, giving the value the list had when the user started editing. This accurately expresses the user's intent, and if two users edit the same list around the same time, it prevents a situation where the second change accidentally reverts the first one without either user noticing.

Omitting old is appropriate where the intent really is a new complete list rather than an edit, for example in an integration that syncs the list from an external source of truth.

Permitted values

Not every possible group-setting value is a valid configuration for a given group-based setting. For example, as a security hardening measure, some administrative permissions should never be exercised by guest users, and the system group for all users, including guests, should not be offered to users as an option for those settings.

Others have restrictions to only permit system groups due to UI components not yet having been migrated to support a broader set of values. In order to avoid this configuration ending up hardcoded in clients, every permission setting using this framework has an entry in the server_supported_permission_settings section of the POST /register response.

Clients that support mutating group-settings values must parse that part of the register payload in order to compute the set of permitted values to offer to the user and avoid server-side errors when trying to save a value.

Note specifically that the allow_everyone_group field, which determines whether the setting can have the value of "all user accounts, including guests" also controls whether guests users can exercise the permission regardless of their membership in the group-setting value.